Domain: PROCEDURE
Command description
The TRANSMIT-BY-STREAM command carries out a variable transmission initiated from the client side, to or from the server which is addressed and using the specified S variable stream.
TRANSMIT-BY-STREAM first sends the variable specified in VARIABLE-NAME to the SDF-P controller, and receives data back from SDF-P in the variables specified in RETURN-VARIABLE-NAME.
If *VARIABLE is assigned to the S variable stream in an ASSIGN-STREAM command, then the variables contained in the RETURN-VARIABLE-NAME and RET-CONTROL-VAR-
NAME of the TRANSMIT-BY-STREAM command are overwritten by the variables which have the same name in the ASSIGN-STREAM command.
If *DUMMY is assigned to the S variable stream, the command sends back a return code indicating that nothing has been changed.
The execution sequence is described in chapter “S variable streams”.
Format
TRANSMIT-BY-STREAM |
STREAM-NAME = <structured-name 1..20> ,VARIABLE-NAME = *NONE / <composed-name 1..255> ,RETURN-VARIABLE-NAME = *SAME / *NONE / <composed-name 1..255> ,CONTROL-VAR-NAME = *NONE / <composed-name 1..255> ,RET-CONTROL-VAR-NAME = *SAME / *NONE / <composed-name 1..255> |
Operands
STREAM-NAME = <structured-name 1..20>
Name of the S variable stream in which the variable is transmitted.
VARIABLE-NAME =
The S variable sent by the transmission (the “output” variable).
VARIABLE-NAME = *NONE
No S variable is transmitted.
If the variable stream is assigned to a variable, the assigned S variable remains unchanged.
VARIABLE-NAME = <composed-name 1..255>
Name of the S variable, which is sent to the server.
The specified S variable must be a structure, containing all the data which the client must send. If an empty S variable is specified, and the variable stream is assigned to
*VARIABLE(...), an empty list element is created.
RETURN-VARIABLE-NAME =
Name of the return variable for the transmission.
RETURN-VARIABLE-NAME = *SAME
The return variable is the S variable which was sent.
The transmitted S variable is first written to the server, after which the server overwrites it with the return data.
For example, if the S variable stream is assigned to *VARIABLE(...), then the transmitted variable is first written into the S variable (list) specified by the VARIABLE-NAME operand in the ASSIGN-STREAM command; this is then overwritten by the S variable (list) specified by RETURN-VARIABLE-NAME.
RETURN-VARIABLE-NAME = *NONE
The client does not expect the return of any return variable.
However, if the S variable stream is assigned to *VARIABLE(...), the specified return variable (list element) is nevertheless handled as a though a return variable had been specified in TRANSMIT-BYSTREAM.
RETURN-VARIABLE-NAME = <composed-name 1..255>
Name of the S variable which is sent back by the server after the TRANSMIT-BY-STREAM has been executed.
If RETURN-VARIABLE-NAME =VARIABLE-NAME, the actions performed are the same as for RETURN-VARIABLE-NAME = *SAME.
If the server does not send back a RETURN-VARIABLE, the variable remains unaltered.
CONTROL-VAR-NAME =
Specifies the control data for the server.
This data is identified by a standard header, the format and structure of which are detailed after the description of the command return codes.
The nature of this control data is determined by the possible servers. The control data is not part of the user data. Separate field names are reserved within the server for this process; e.g. the FHS subsystem (TPR display) defines variables which, among other things, define panels which must be loaded and in which FHS performs its functions.
CONTROL-VAR-NAME = *NONE
No control variable is specified.
If the server requires control variables, then either standard variables will be used (when possible) or the transmission will be rejected.
CONTROL-VAR-NAME = <composed-name 1..255>(...)
Name of the S variable which contains the control data.
The specified S variable must be a structure.
Note
If the server requests a control variable and the caller either specifies none or specifies an incomplete one, there are two possible results of the transmission:
If the missing control data is optional for the controlling server, the transmission will be carried out using the default settings.
If the missing control data is mandatory for the controlling server, the transmission will be terminated, with an error message.
RET-CONTROL-VAR-NAME =
Specifies the S variable by which the return control data can be sent to the client.
RET-CONTROL-VAR-NAME = *SAME
Specifies the same S variable as for CONTROL-VAR-NAME.
The same rules apply in this case as when VARIABLE-NAME and RETURN-VARIABLE-NAME are both specified.
RET-CONTROL-VAR-NAME = *NONE
The client expects no return control data.
RET-CONTROL-VAR-NAME = <composed-name 1..255>
Name of the S variable by which the server transmits the return control data.
The specified S variable must be a structure.
If the server does not send back a RET-CONTROL-VARIABLE, the variable remains unaltered.
Command return codes
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
| 0 | CMD0001 | No error | |
| 1 | 0 | CMD0001 | Variable stream is assigned to *DUMMY; no transmission, variable remains unchanged |
| 2 | 0 | SDP0512 | Server is no longer active. Data stream is assigned to *DUMMY |
| 2 | 0 | SDP0531 | Warning returned by server; process continuing |
| 1 | CMD0202 | Syntax error | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 64 | CMD0216 | Do not have required privilege | |
| 64 | SDP0091 | Semantic error Guaranteed messages: SDP1008 | |
| 64 | SDP0532 | Server error; command rejected | |
| 64 | SDP0534 | Internal server error; command terminated. Server link terminated following unexpected event or due to shortage or absence of system resources | |
| 64 | SDP0517 | Variable stream does not exist | |
| 64 | SDP0522 | Transmitted data is incompatible with the format that the server handles | |
| 64 | SDP1132 | Variable name too long | |
| 130 | SDP0099 | No further address space available |
Note
The following should be noted for return code SDP0512: if S variable streams which are dependent on the calling procedure are assigned to procedure-local variables, then after the procedure end they can no longer be used. Any subsequent transmission is ignored, with a warning, and the S variable stream is reset to *DUMMY.
Example
/DECLARE-VARIABLE OPS-VAR(TYPE=*STRUCTURE),MULTIPLE-ELEMENTS=*LIST /DECLARE-VARIABLE OPS-VAR1(TYPE=*STRUCTURE) /ASSIGN-STREAM SYSINF,TO=*VARIABLE(OPS-VAR) /ASSIGN-SYSOUT TO=#ERROR-SYSOUT /TRANSMIT-BY-STREAM SYSINF, VARIABLE=OPS-VAR1, RETURN-VARIABLE=*NONE
Standard header
SDF-P provides a standard header as a reserved structure layout. This standard header can be defined as the first element of the control variable structure.
Its layout is declared in a procedure which must be called by an INCLUDE-PROCEDURE.
This procedure is supplied in the $TSOS.SYSPRC.SDF-P-BASYS.025 library, in the FHDR element. It looks as follows:
/set-proc-options "caller=include not supported by sdf-p-basys"
/begin-parameter-declaration
/ declare-parameter -
/ "------------ std param --------------------------------*"-
/(PREFIX (init='SYSSDP') -
/,INCLUDE-FORM (init='LAYOUT') "/INITIALIZE" -
/,VARIABLE-NAME(init='') -
/ "------------ include specific param -------------------*"-
/,UNIT (init='') -
/,FUNCTION (init='') -
/,VERSION (init=0) -
/,SUBCODE2 (init=0) -
/,SUBCODE1 (init=0) -
/,MAINCODE (init='CMD0001') -
/)
/end-parameter-declaration
/
/if (not is-sdf-p() )
/ exit-procedure error=*yes(subcode1=41,maincode=cmd2241)
/end-if
/
/if (upper-case(INCLUDE-FORM) == 'LAYOUT')
/
/begin-structure name=&PREFIX.IFID-MDL,scope=proc
/ declare-element -
/(UNIT (type=string) -
/,FUNCTION (type=string) -
/,VERSION (type=integer) -
/)
/end-structure
/begin-structure name=&PREFIX.RETC-MDL,scope=proc
/ declare-element -
/(SUBCODE2 (type=integer) -
/,SUBCODE1 (type=integer) -
/,MAINCODE (type=string) -
/)
/end-structure
/begin-structure name=&PREFIX.FHDR,scope=proc
/ declare-element INTERFACE-ID(type=structure(&PREFIX.IFID-MDL))
/ declare-element RETURNCODE (type=structure(&PREFIX.RETC-MDL))
/end-structure
/
/else-if (upper-case(INCLUDE-FORM) == 'INITIALIZE')
/
/ if (VARIABLE-NAME == '')
/ write-text '% mandatory parameter variable-name missing.'
/ raise-error
/ end-if
/ declare-variable PARAM(type=string)
/ for PARAM = ('UNIT','FUNCTION')
/ &VARIABLE-NAME..INTERFACE-ID.&PARAM = &PARAM
/ end-for
/ &VARIABLE-NAME..INTERFACE-ID.VERSION = INTEGER(VERSION)
/ for PARAM = ('SUBCODE2','SUBCODE1')
/ &VARIABLE-NAME..RETURNCODE.&PARAM = INTEGER(&PARAM)
/ end-for
/ &VARIABLE-NAME..RETURNCODE.MAINCODE = MAINCODE
/
/else
/ write-text '% form=&INCLUDE-FORM not supported; include aborts'
/ raise-error
/end-if
/exit-procedure
UNIT (TYPE = *STRING)Description of the procedure parameters
Name of the server which is defining the control variable. This name should be identical with that defined in ASSIGN-STREAM.
FUNCTION (TYPE = *STRING)
Name of the function for which the server is defining the control variable layout. This name is defined by the server and passed on.
VERSION (TYPE = *INTEGER)
Version of the control variable. This allows the server to support earlier versions of the control variable compatibly.
SUBCODE2 (TYPE = *INTEGER)
Subcode2, which is returned by the server (in RET-CONTROL-VAR-NAME).
SUBCODE1 (TYPE = *INTEGER)
Subcode1, which is returned by the server (in RET-CONTROL-VAR-NAME).
MAINCODE (TYPE = *STRING)
Message ID, which is returned by the server (in RET-CONTROL-VAR-NAME).
The same conventions apply for the SUBCODE2, SUBCODE1 and MAINCODE operands as for the command return code.
The routers (TRANSMIT-BY-STREAM and TRANSVV) do not use these variables. Warnings and error messages from TRANSMIT-BY-STREAM and TRANSVV depend on the internal return code, which is returned by the server and not by means of these control variables.
Consequently, these control variables should be returned by the server, to provide a more precise error message than those from TRANSMIT-BY-STREAM and TRANSVV.
Note
The error and warning information which is written into these control variables should agree with the server’s internal return code. For example, this means that if TRANSMIT-BY-STREAM returns the error class SUBCODE2=0,SUBCODE1=64 and MAINCODE=SDP0532, there will also be an error code in the return control variable; or, if SUBCODE2=2,SUBCODE1=0 and MAINCODE=SDP0531 is returned, then the return control variable should (also) contain a warning, and so on. However, the maintenance of this consistency is the responsibility of the server.