$Sock_Set

Change parameter or setting on one or all sockets

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_Set is the Set method.

$Sock_Set changes the value of a parameter or setting on one or all relevant sockets.

It is also a callable function.

Syntax

[%old =] = $Sock_Set(sockNum, keyword, [value])

Syntax terms

%old	A string containing either a previous value of parameter or setting, or, if sockNum argument is -1, count of sockets changed.
sockNum	The socket number; or it is -1, which indicates that the change affects all relevant sockets.
keyword	Any of the keywords from the parameter and settings list provided below. Some of these keywords require that the socket be OPEN for the setting to take effect; for these, if the socket is not OPEN, the operation is ignored.
value	The value to which the parameter or setting should be changed. If the keyword is self-defining, this argument may be omitted or left null. Valid values are explained in the keyword list provided below.

Eligible keyword and value settings for $Sock_Set

Keyword	Meaning
BINARY	Do not translate bytes sent and received. The default is taken from the socket's port definition. For more information about this setting, see BINARY (JANUS DEFINE parameter). This requires that the socket be OPEN.
CHAR	Translate strings sent and received with $Sock_ functions between the internal representation within Model 204 (EBCDIC) and the character representation used by the remote end of the connection. The default is taken from the socket's port definition. For more information about this setting, see CHAR (JANUS DEFINE parameter). This requires that the socket be OPEN.
CLOSE	Close socket at end of request; this is the default for CLSOCK sockets. This applies to any in-use socket.
NOCLOSE	Close socket at LOGOUT, not at end of request. This is the default for SRVSOCK sockets. This applies to any in-use socket.
LINEND	This parameter must have a value specified as NONE or <hexchars> as the value argument. NONE indicates that a linend string is not set, and one must be provided before or with the next $Sock_SendLn call. Follow each $Sock_SendLn call with the indicated string of bytes; no translation is done on these hex bytes, whether BINARY or CHAR is set. The special value NONE disables any previously defined LINEND string. The default is taken from the socket's port definition. For more information about this setting, see LINEND (JANUS DEFINE parameter). This requires that the socket be OPEN.
ONRESET	This setting must have one of the following values specified as the value argument: CANCEL, to indicate that socket reset conditions are handled by cancelling the User Language request. CANCELC, to indicate that socket reset conditions are handled depending on whether the given operation can complete. Those which cannot complete are handled by cancelling the User Language request. For those that can complete, the request continues as usual to the next statement, and an error indicator is returned by the $function encountering the condition. The last error indication can also be retrieved using the $Sock_ErrInfo function. CONTINUE, to indicate that when a socket reset condition is found, the request continues as usual to the next statement, and an error indicator is returned by the $function encountering the condition. The last error indication can also be retrieved using the $Sock_ErrInfo function. LABEL, to indicate that all socket reset conditions are handled by the label established by the most recent $Sock_OnReset call, or that the request is cancelled if there is no ONRESET label. LABELC, to indicate that socket reset conditions are handled depending on whether the given operation can complete. Those which cannot complete are handled by the label established by the most recent $Sock_OnReset call, or that the request is cancelled if there is no ONRESET label. For those that can complete, the request continues as usual to the next statement, and an error indicator is returned by the $function encountering the condition. The last error indication can also be retrieved using the $Sock_ErrInfo function. The default is LABEL. See "Handling connection errors and RESET sockets". This applies to any in-use socket.
PRSTOK	This parameter must have a value specified as either NONE or [AMBIG|]<hexchars>[|<hexchars>]... as the value argument. NONE indicates that a separator string is not set, and one must be provided before or with the next $Sock_RecvPrs call. The specified set of hexadecimal strings are used as "break" strings for returning subsequent strings with the $Sock_RecvPrs function. If and only if one string is a prefix of another, AMBIG| must be used at the start. The default is taken from the socket's port definition. For more information about this setting, see PRSTOK (JANUS DEFINE parameter). This requires that the socket be OPEN.
RECVLIM	A number ranging from 0 to 2,147,483,647, specifying the limit on total bytes of data plus "parse tokens" scanned by subsequent receive operations. The default is 0, indicating no limit. RECVLIM is discussed in "Lengths: maximum, minimum, truncation, RECVLIM" and "Lengths: maximum, truncation, RECVLIM". This requires that the socket be OPEN.
TIMEOUT	Number indicating the port TIMEOUT time, in seconds. The default is taken from the socket's port definition. This requires that the socket be OPEN.
XTAB	The EBCDIC-to-ASCII, ASCII-to-EBCDIC, and character-entity translation tables to be used for the socket. The default is taken from the socket's port definition For more information about this setting, see XTAB (JANUS DEFINE parameter). This requires that the socket be OPEN.

Usage notes

• If the sockNum argument is -1, indicating that all relevant sockets are affected by the $Sock_Set call, the return string will be the number of sockets affected by the change. If sockNum is the number of an in-use socket, the returned string contains the previous value of the parameter or setting or the string RESET if the socket must be OPEN and it is not. If $Sock_Set is invoked with a single socket (that is, not -1) as the sockNum argument, and that socket is RESET, the results depend on several factors:
  • If the keyword argument is ONRESET, the operation is performed normally, and there is no indication of the fact that the socket is RESET.
  • Otherwise, if the keyword argument is a keyword that does not require an OPEN socket, and ONRESET CONTINUE, CANCELC, or LABELC is in effect for the socket, the string RESET is returned and the last error information is set.
  • Otherwise, if ONRESET CONTINUE is in effect for the socket, the string RESET is returned and the last error information is set.
  • Otherwise the request is canceled or the ONRESET label is jumped to, as explained in "Handling connection errors and RESET sockets".
• The value argument can be omitted for keywords that are self-defining:

  %t = $Sock_Set(%sockno, 'BINARY')

  This sets the socket to binary mode, in which bytes sent over the connection are not translated in any way. "Self-defining" keywords can also be given a value argument, which allows you to restore a previous value:

  Foo: Subroutine %t = $Sock_Set(%sockno, 'BINARY') ... %t = $Sock_Set(%sockno, 'BINARY', %t) Return

  The value argument is required for keywords that need a value:

  %t = $Sock_Set(%sockno, 'LINEND', 'NONE')

  This disables the sending of the line-end string.

• You can use $Sock_Info to obtain the current value of the setting of any of the keywords that can be specified as the keyword argument of $Sock_Set.