JALWiccan: Automatically generated page update

2018-09-21T00:00:36Z

Automatically generated page update

← Older revision		Revision as of 00:00, 21 September 2018
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_Set}}		{{DISPLAYTITLE:$Sock_Set}}
	<span class="pageSubtitle">Change parameter or setting on one or all sockets</span>		<span class="pageSubtitle">Change parameter or setting on one or all sockets</span>
	<p class="warn"><b>Note: </b>~~Most Sirius~~ $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented
	methods. The OO equivalent for <var>$Sock_Set</var> is the <var>[[Set (Socket function)\|Set]]</var> method.</p>		methods. The OO equivalent for <var>$Sock_Set</var> is the <var>[[Set (Socket function)\|Set]]</var> method.</p>

JAL at 21:55, 23 July 2013

2013-07-23T21:55:47Z

← Older revision		Revision as of 21:55, 23 July 2013
Line 2:		Line 2:
	<span class="pageSubtitle">Change parameter or setting on one or all sockets</span>		<span class="pageSubtitle">Change parameter or setting on one or all sockets</span>
	<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
	methods. ~~There is currently no direct~~ OO equivalent for ~~this~~ $function.</p>		methods. The OO equivalent for <var>$Sock_Set</var> is the <var>[[Set (Socket function)\|Set]]</var> method.</p>

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

JALWiccan: Automatically generated page update

2013-07-19T18:59:28Z

Automatically generated page update

← Older revision		Revision as of 18:59, 19 July 2013
Line 1:		Line 1:
	{{DISPLAYTITLE:$Sock_Set}}		{{DISPLAYTITLE:$Sock_Set}}
	<span class="pageSubtitle">Change parameter or setting on one or all sockets</span>		<span class="pageSubtitle">Change parameter or setting on one or all sockets</span>
	<p class="~~warning~~">Most Sirius $functions have been deprecated in favor of Object Oriented		<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
	methods. There is currently no direct OO equivalent for this $function.</p>		methods. There is currently no direct OO equivalent for this $function.</p>

Admin: 1 revision

2012-01-20T02:53:46Z

1 revision

← Older revision	Revision as of 02:53, 20 January 2012
(No difference)

JAL at 02:42, 20 January 2012

2012-01-20T02:42:48Z

New page

{{DISPLAYTITLE:$Sock_Set}}
Change parameter or setting on one or all sockets
Most Sirius $functions have been deprecated in favor of Object Oriented
methods. There is currently no direct OO equivalent for this $function.

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

It is also a [[Notation conventions for methods#Callable functions|callable]] function.

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

===Syntax terms===
<table class="syntaxTable">
<tr><th>%old</th>
<td>A string containing either a previous value of parameter or setting, or, if <var class="term">sockNum</var> argument is -1, count of sockets changed. </td></tr>
<tr><th>sockNum</th>
<td>The socket number; or it is -1, which indicates that the change affects all relevant sockets. </td></tr> <tr><th>keyword</th>
<td>Any of the keywords from the parameter and settings list provided [[#Eligible keyword and value settings for $Sock_Set|below]]. Some of these keywords require that the socket be <var>[[Janus Sockets User Language coding considerations#Socket states: OPEN, RESET, FIN indicator|OPEN]]</var> for the setting to take effect; for these, if the socket is not <var>OPEN</var>, the operation is ignored. </td></tr>
<tr><th>value</th>
<td>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 [[#Eligible keyword and value settings for $Sock_Set|below]]. </td></tr>
</table>

===Eligible keyword and value settings for $Sock_Set===
<table class="syntaxTable">
<tr><th>Keyword</th>
<th>Meaning</th></tr>
<tr><th>BINARY</th>
<td>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 <var>[[Janus Sockets User Language coding considerations#Socket states: OPEN, RESET, FIN indicator|OPEN]]</var>. </td></tr>
<tr><th>CHAR</th>
<td>Translate strings sent and received with $Sock_ functions between the internal representation within <var class="product">Model 204</var> (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 <var>OPEN</var>. </td></tr>
<tr><th>CLOSE</th>
<td>Close socket at end of request; this is the default for <var>[[JANUS DEFINE#type|CLSOCK]]</var> sockets.

This applies to any in-use socket. </td></tr>
<tr><th>NOCLOSE</th>
<td>Close socket at <var>LOGOUT</var>, not at end of request. This is the default for <var>[[JANUS DEFINE#type|SRVSOCK]]</var> sockets.

This applies to any in-use socket. </td></tr>
<tr><th>LINEND</th>
<td>This parameter must have a value specified as <code>NONE</code> or <code><hexchars></code> as the <var class="term">value</var> argument.
<var>NONE</var> indicates that a linend string is not set, and one must be provided before or with the next <var>[[$Sock_SendLn]]</var> call.
Follow each <var>$Sock_SendLn</var> call with the indicated string of bytes; no translation is done on these hex bytes, whether <var>BINARY</var> or <var>CHAR</var> is set. The special value <code>NONE</code> disables any previously defined
<var>LINEND</var> 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 <var>OPEN</var>. </td></tr>
<tr><th>ONRESET</th>
<td>This setting must have one of the following values specified as the <var class="term">value</var> argument:

<ul>
<li><var>CANCEL</var>, to indicate that socket reset conditions are handled by cancelling the <var class="product">User Language</var> request.
<li><var>CANCELC</var>, 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 <var
class="product">User Language</var> 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 <var>[[$Sock_ErrInfo]]</var> function.
<li><var>CONTINUE</var>, 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 <var>$Sock_ErrInfo</var> function.
<li><var>LABEL</var>, to indicate that all socket reset conditions are handled by the label established by the most recent <var>[[$Sock_OnReset]]</var> call, or that the request is cancelled if there is no <var>ONRESET</var> label.
<li><var>LABELC</var>, 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 <var>$Sock_OnReset</var> call, or that the
request is cancelled if there is no <var>ONRESET</var> 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 <var>[[$Sock_ErrInfo]]</var> function.
</ul>

The default is <var>LABEL</var>. See [[Janus Sockets User Language coding considerations#Handling connection errors and RESET sockets|"Handling connection errors and RESET sockets"]].

This applies to any in-use socket. </td></tr>
<tr><th>PRSTOK</th>
<td>This parameter must have a value specified as either <code>NONE</code> or <code>[AMBIG|]<hexchars>[|<hexchars>]...</code> as the <var class="term">value</var> argument. <var>NONE</var> indicates that a separator string is not set, and one must be provided before or with the next <var>[[$Sock_RecvPrs]]</var> call.
The specified set of hexadecimal strings are used as "break" strings for returning subsequent strings with the <var>$Sock_RecvPrs</var> function. If and only if one string is a prefix of another, <code>AMBIG|</code> 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 <var>OPEN</var>. </td></tr>
<tr><th>RECVLIM</th>
<td>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.

<var>RECVLIM</var> is discussed in [[$Sock_Recv#Lengths: maximum, minimum, truncation, RECVLIM|"Lengths: maximum,
minimum, truncation, RECVLIM"]] and [[$Sock_RecvPrs#Lengths: maximum, minimum, truncation, RECVLIM|"Lengths: maximum, truncation, RECVLIM"]].
This requires that the socket be <var>OPEN</var>. </td></tr>
<tr><th>TIMEOUT</th>
<td>Number indicating the port <var>[[TIMEOUT (JANUS DEFINE parameter)|TIMEOUT]]</var> time, in seconds.

The default is taken from the socket's port definition.

This requires that the socket be <var>OPEN</var>. </td></tr>
<tr><th>XTAB</th>
<td>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 <var>OPEN</var>. </td></tr>
</table>

==Usage notes==
<ul>
<li>If the <var class="term">sockNum</var> argument is -1, indicating that all relevant sockets are affected by the <var>$Sock_Set</var> call, the return string will be the number of sockets affected by the change.
If <var class="term">sockNum</var> is the number of an in-use socket, the returned string contains the previous value of the parameter or setting or the string <code>RESET</code> if the socket must be <var>OPEN</var> and it is not.
If <var>$Sock_Set</var> is invoked with a single socket (that is, not -1) as the <var class="term">sockNum</var> argument, and that socket is <code>RESET</code>, the results depend on several factors:

<ul>
<li>If the <var class="term">keyword</var> argument is <code>ONRESET</code>, the operation is performed normally, and there is no indication of the fact that the socket is <code>RESET</code>.
<li>Otherwise, if the <var class="term">keyword</var> argument is a keyword that does not require an <var>OPEN</var> socket, and <var>ONRESET CONTINUE</var>, <var>CANCELC</var>, or <var>LABELC</var> is in effect for the socket, the string <code>RESET</code> is returned and the last error information is set.
<li>Otherwise, if <var>ONRESET CONTINUE</var> is in effect for the socket, the string <code>RESET</code> is returned and the last error information is set. <li>Otherwise the request is canceled or the <var>ONRESET</var> label is jumped to, as explained in [[Janus Sockets User Language coding considerations#Handling connection errors and RESET sockets|"Handling connection errors and RESET sockets"]].
</ul>

<li>The <var class="term">value</var> 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 <var class="term">value</var> argument, which allows you to restore a previous value:
Foo: Subroutine
%t = $Sock_Set(%sockno, 'BINARY')
...
%t = $Sock_Set(%sockno, 'BINARY', %t)
Return 
The <var class="term">value</var> argument is required for keywords that need a value:
%t = $Sock_Set(%sockno, 'LINEND', 'NONE') 
This disables the sending of the line-end string.

<li>You can use <var>[[$Sock_Info]]</var> to obtain the current value of the setting of any of the keywords that can be specified as the <var class="term">keyword</var> argument of <var>$Sock_Set</var>.
</ul>

[[Category: Janus Sockets $functions]]

$Sock Set - Revision history

JALWiccan: Automatically generated page update

JAL at 21:55, 23 July 2013

JALWiccan: Automatically generated page update

Admin: 1 revision

JAL at 02:42, 20 January 2012