Revision as of 21:35, 8 November 2011
<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 (Socket function). |
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.