SETO: Set option

SETO: Set option

z/OS MVS Program Management: Advanced Facilities
SA23-1392-00

SETO specifies options for processing and module attributes. Each option is set at either the dialog or workmod level by providing a token in the call. The options that can be specified are listed in Setting options with the regular binder API.

The syntax of the SETO call is:

[symbol]

IEWBIND

FUNC=SETO

[,VERSION=version]
[,RETCODE=retcode]
[,RSNCODE=rsncode]
[,WORKMOD=workmod]
[,DIALOG=dialog]
,OPTION=option
,OPTVAL=optval
[,PARMS=parms]

FUNC=SETO: Specifies that you are requesting specific processing options or module attributes for a dialog or workmod.
VERSION=1 | 2 | 3 | 4 | 5 | 6 | 7 | 8: Specifies the version of the parameter list to be used. The default value is VERSION=1.
Note: If VERSION=1 is specified for the SETO call, PARMS cannot be specified as a macro keyword. The parameter list ends with the OPTVAL parameter (with the high-order bit set). This exception is for version 1 only.
RETCODE=retcode — RX-type address or register (2-12): Specifies the location of a fullword integer that is to receive the return code returned by the binder.
RSNCODE=rsncode — RX-type address or register (2-12): Specifies the location of a 4-byte hexadecimal string that is to receive the reason code returned by the binder.
WORKMOD=workmod — RX-type address or register (2-12): Specifies the location of an 8-byte area that contains the workmod token for this request. WORKMOD and DIALOG are mutually exclusive. To set the options at the workmod level, provide the WORKMOD token.
DIALOG=dialog — RX-type address or register (2-12): Specifies the location of an 8-byte area that contains the appropriate dialog token. WORKMOD and DIALOG are mutually exclusive. To set the options at the dialog level, provide the DIALOG token.
OPTION=option — RX-type address or register (2-12): Specifies the location of an 8-byte varying character string that contains an option keyword. Except for CALLIB, all keywords can be truncated to three characters. See Setting options with the regular binder API for a complete list of keywords.
OPTVAL=optval — RX-type address or register (2-12): Specifies the location of a varying character string that contains a value or a list of values for the specified option.
PARMS=parms — RX-type address or register (2-12): Specifies the location of a varying character string that contains a list of option specifications separated by commas.

Processing notes

Option values are coded as value or (value1,value2). A list of values is enclosed in parentheses. A value containing special characters is enclosed in single quotation marks. An imbedded single quotation mark is coded as two consecutive single quotation marks. Special characters include all EBCDIC characters other than upper and lower case alphabetics, numerics, national characters (@ # $), and the underscore. YES and NO values can be abbreviated Y and N, respectively.

Options specified for a workmod override any corresponding options specified for that dialog. Options specified at the dialog level override the corresponding system defaults, and apply to all workmods within the dialog unless overridden. If INTENT=ACCESS, these keywords are not allowed: ALIGN2, CALL, CALLIB, EDIT, LET, MAP, OVLY, RES, TEST, XCAL, and XREF.

The options list specified in the PARMS= parameter is a character string identical to the PARM= value defined in the "Binder options reference" chapter of z/OS MVS Program Management: User's Guide and Reference, with the following restrictions:

The list is not enclosed with apostrophes or parentheses
Environmental options cannot be specified on SETO. See the list of environmental options in Setting options with the binder API
The EXITS and OPTIONS options are also not allowed in this list.

The OPTION and OPTVAL operands are used together to specify a single option and its value.

None of the environmental options can be specified. See Setting options with the binder API.
The following invocation options may not be specified on the OPTION/OPTVAL operands of SETO because they are really mapped to something different: EXITS, OPTIONS, REFR, RENT, and the YES, NO, or default values for REUS.
The negative option format (for example, NORENT) is not allowed. The corresponding option with a value must be used (for example, OPTION=REUS,OPTVAL=SERIAL).
An option specified using the OPTION and OPTVAL operands overrides any value for that same option specified within the PARMS operand.

You can specify a z/OS UNIX System Services file as the CALLIB parameter value on a SETO call.

Return and reason codes

The common binder API reason codes are shown in Table 1.

Return Code	Reason Code	Explanation
00	00000000	Normal completion.
08	83000109	One or more options designated as environmental have been specified on SETO. Option ignored.
08	83000111	An option you specified can not be altered as it is an environmental option (for example, EXITS)
12	83000100	Neither dialog token nor workmod token were specified. Request rejected.
12	83000106	The option specified is invalid for a workmod specified with INTENT=ACCESS. Request rejected.
12	83000107	Invalid option keyword specified. Request rejected.
12	83000108	The option value is invalid for the specified keyword. Request rejected.
12	83000113	An option you specified is valid only for the STARTD function. The request is rejected.

Parameter list

If your program does not use the IEWBIND macro, place the address of the SETO parameter list in general purpose register 1.

Table 1. SETO parameter list

`PARMLIST`	`DS`	`0F`
	`DC`	`A(SETO)`	Function code
	`DC`	`A(RETCODE)`	Return code
	`DC`	`A(RSNCODE)`	Reason code
	`DC`	`A(DIALOG)`	Dialog token
	`DC`	`A(WORKMOD)`	Workmod token
	`DC`	`A(OPTION)`	Option keyword
	`DC`	`A(OPTVAL)`	Option value
	`DC`	`A(PARMS)`	Options list
`SETO`	`DC`	`H'20'`	SETO function code
	`DC`	`H'version'`	Interface version number

Note: X'80000000' must be added to either the OPTION parameter (for Version 1) or the PARMS parameter (for Version 2 or higher).