Set (Socket function)

<section begin=dpl_desc/><section end=dpl_desc/>

Set is a member of the Socket class.

This method changes the value of a parameter or setting on the indicated socket. The Set function, which may be invoked with a Call statement, has an effect similar to $Sock_Set.

Syntax

[%old =] %socko:Set(keyword, [value])

Syntax terms

%old	If specified, string that is to contain either: The previous value of the parameter or setting that is to be set by this method. The string RESET, if the socket must be OPEN and it is not.
%socko	A variable or an expression that is a reference to a Socket object.
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 the parameter or setting should be changed to. If the keyword is self-defining, this argument may be omitted or left null. Valid values are explained in the keyword list provided below. Keyword Meaning AUDTERM Terminal output is sent to the audit trail. Not valid for CLSOCK sockets. The default is taken from the socket's port definition (see AUDTERM). This requires that the socket be OPEN. NOAUDTERM Non-compiler terminal output is not sent to the audit trail. Not valid for CLSOCK sockets. The default is taken from the socket's port definition (see NOAUDTERM). This requires that the socket be OPEN. BINARY Do not translate bytes sent and received. The default is taken from the socket's port definition. This requires that the socket be OPEN. CHAR Translate strings sent and received with Socket methods 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. 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. Note: This option is not valid as of Sirius Mods version 6.6. NOCLOSE Close socket at LOGOUT, not at end of request; this is the default for SRVSOCK sockets. This applies to any in-use socket. Note: This option is not valid as of Sirius Mods version 6.6. LINEND This parameter must have an accompanying value (NONE or hexchars), specified as the value argument of the Set method. NONE indicates that a linend string is not set, and one must be provided before or with the next SendWithLineEnd method call. NONE disables any previously defined LINEND string. hexchars indicates that each SendWithLineEnd call is to have the hexchars string of bytes appended. No translation is done on these hex bytes, whether BINARY or CHAR is set. The LINEND default is taken from the socket's port definition. This requires that the socket be OPEN. ONRESET This setting, which applies to any in-use socket, must be accompanied by one of the following values, specified as the value argument of the Set method. CANCEL Socket reset conditions are handled by cancelling the User Language request. CANCELC Socket reset conditions are handled depending on whether the given operation can complete. Operations that cannot complete are handled by cancelling the User Language request. If the operation can complete, the request continues as usual to the next statement, and an error indicator is returned by the method that encountered the condition. The last error indicator can also be retrieved using the ErrInfo method. CONTINUE If a socket reset condition is encountered, the request continues as usual to the next statement, and an error indicator is returned by the method that encountered the condition. The last error indication can also be retrieved using the ErrInfo method. LABEL All socket reset conditions are handled by the label established by the most recent OnReset method call. If there is no ONRESET label, the request is cancelled. LABELC How the socket reset conditions are handled depends on whether the given operation can complete. Operations that cannot complete are handled by the label established by the most recent OnReset method call. If there is no ONRESET label, the request is cancelled. For operations that can complete, the request continues as usual to the next statement, and an error indicator is returned by the method that encounters the reset condition. The last error indicator can also be retrieved using the ErrInfo method. The default is LABEL. See "Handling connection errors and RESET sockets". PRSTOK This parameter must have a value (NONE or [AMBIG|]hexchars[|hexchars]...), specified as the value argument of the Set method: NONE indicates that a separator string is not set, and one must be provided before or with the next ReceiveAndParse method call. hexchars are the specified set of hexadecimal strings to be used as "break" strings for returning subsequent strings with the ReceiveAndParse method. 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 (see PRSTOK). 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 XTAB table to use is specified as the value argument of the Set method. The default is taken from the socket's port definition (see XTAB). This requires that the socket be OPEN.

Usage notes

• The Set method differs from $Sock_Set as follows:
  • $Sock_Set may optionally be applied to "all relevant single sockets," but the Set method applies only to a single Socket object.
  • As of version 6.6, the CLOSE and NOCLOSE keywords are not valid options for the Set method. Since Socket objects may persist (Global or Session) beyond a request, and since they are also subject to discard, it is whether or not the object has been discarded that determines whether the socket gets closed at the end of the request.
• If the Set method is invoked for a socket that 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 one which 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 keyword argument can be omitted for keywords that are self-defining:

  %t = %sock:Set('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 accompanied by a value argument, which allows you to restore a previous value:

  FOO: Subroutine %t = %sock:Set('BINARY') ... %t = %sock:Set('BINARY', %t) Return

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

  %t = %sock:Set('LINEND', 'NONE')

  This disables the sending of the line-end string.

• You can use the Info method to obtain the current value of the setting of any of the keywords that can be specified as the keyword argument of the Set method.