SETO call

The SET Options (SETO) call allows IMS application programs to set processing options. The SETO call can also be used to set processing options for Spool API functions.

Format

Call Name	DB/DC	DBCTL	DCCTL	DB Batch	TM Batch
SETO	X		X

Parameters

i/o pcb

Specifies the I/O PCB, the first PCB address in the list that is passed to the program. This parameter is an input and output parameter.

alternate pcb

Specifies the TP or alternate PCB to be used for the call. These parameters are input and output parameters.

aib

Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.

The following fields must be initialized in the AIB:

AIBID: Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN: AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1: Resource name. This 8-byte, left-justified field must contain the PCB name IOPCBbbb (if the TP PCB is used), or the name of an alternate PCB (if an alternate PCB is used).
AIBOALEN: I/O area length. This field must contain the length of the I/O area that is specified in the call list.

i/o area

Specifies the I/O area to be used for the call. This parameter is an output parameter. If you specify an options list that contains advanced print functions, you must specify an I/O area. If you use APPC options, the I/O area parameter is optional.

For advanced print function options the I/O area must be at least 4 KB. If the I/O area including the LLZZ or LLLLZZ prefix is less than 4096 bytes in length, an AJ status code is returned. Once the text units area built in the I/O area, the area must not be copied to a new area. The I/O area passed on the SETO call must contain a LLZZ or, if PL/I, a LLLLZZ prefix.

LLLL applies only to DL/I call interface.

options list

Specifies several option keywords. This input parameter is required. The options in the list are separated by commas and cannot contain embedded blanks. Processing for the options list terminates when the first blank in the list is reached or when the specified options list length has been processed. You can specify options for advanced print functions or for APPC. The options you can specify are described in "Advanced print function options" and "APPC options".

The format for the options list is as follows:

LL or LLLL¹,²	ZZ	keyword=variable1
Halfword length of the options string, including the 4-byte length of LLZZ or LLLLZZ.	Halfword of zero.	SETO options separated by commas.
Note: For application programs that use the PLITDLI interface, the length field is a fullword (LLLL). However, the length of the LLLLZZ field is still considered 4 bytes. If the length field is set to zero, the options list is ignored. IMS TM processes the SETO call as if the `options list` parameter was not specified.

feedback area

Specifies an optional parameter used to return error information about the options list to the application program. This parameter is an output parameter. The amount of information that the application program receives is based on the size of the feedback area. If no feedback area is specified, the status code returned is the only indication of an options list area. If you specify a feedback area 1½ to 2 times the size of the specified options list (a minimum of eight words), IMS TM returns more specific information about errors in the options list.

The format for the feedback area passed to IMS TM in the call list is as follows:

LL or LLLL^1, 2	ZZ
Halfword length of the feedback area, including the 4-byte length of the LLZZ fields.	Halfword of zero.
Note: For application programs that use the PLITDLI interface, the length field is a fullword (LLLL). However, the length of the LLLLZZ field is still considered four bytes. If the length field is set to zero, the feedback area is ignored. IMS TM processes the SETO call as if the `feedback area` parameter was not specified.

The output format returned to the application program from IMS TM for the feedback area is as follows:

LLZZ or LLLLZZ	LL	`feedback area`
The length field as specified in the input format for the feedback area.	Halfword length of the feedback data returned by IMS TM, including the 2-byte LL field.	Data returned by IMS TM. The feedback data generally includes the option keyword found to be in error and a 4-byte EBCDIC code in parentheses that indicates the reason for the error. Multiple errors are separated by commas.

Usage

The SETO call allows you to set processing options.

You can use the SETO call to reduce the overhead necessary to perform parsing and text construction of the OUTPUT descriptors for a data set. If your application program can use a set of descriptors more than once during an installation, the application can use the SETO call to provide print data set characteristics to the Spool API. When the SETO call is processed, it parses the OUTPUT options and constructs the dynamic OUTPUT text units in the work area provided by the application. After the application has received the prebuilt text units, you can use the CHNG call and TXTU= option to provide the print characteristics for the data set without incurring the overhead of parsing and text unit build.

It is not necessary to use the SETO call to prebuild the text units if they can be prebuilt with another programming technique.

Related reading: For more information about Spool API, see IMS Version 15 Application Programming.

In the OTMA environment

An IMS application program that issues a SETO call does not cause IMS to call the Open Transaction Manager Access (OTMA) Prerouting and Destination Resolution exit routines to determine the destination. For information on these exit routines, see IMS Version 15 Exit Routines.

Existing IMS application programs that issue SETO calls might not run as expected because a return code is returned to the program if it is processing an OTMA-originated transaction. Also, APPC/IMS application programs that issue SETO calls might not need modification if they require implicit OTMA support.

A solution to this problem is to use an INQY call before issuing the SETO call. The application program can use the output from the INQY call to determine if a transaction is an OTMA-originated one, to bypass the SETO call.

Advanced print function options

The PRTO= keyword identifies the SETO call as a Spool API request:

Keyword: Description
PRTO=outdes options: Describes the data set processing options as they are specified on the TSO OUTDES statement. The format for the PRTO keyword is as follows:

LL	`outdes options`
Halfword length of the total OUTDES printer options, including the 2-byte length of LL.	Any valid combination of OUTDES printer options, separated by commas.
Note: For information about TSO OUTDES options, see z/OS MVS Programming: Authorized Assembler Services Reference. Some options depend on the release level of MVS.

If z/OS® detects an error in the OUTDES printer options, an AS status code is returned to the application program.

APPC options

The following options are available for the SETO call:

SEND_ERROR

causes the IMS LU Manager to issue SEND_ERROR on the conversation associated with the I/O or alternate PCB when a message is sent. Messages for express PCBs are sent during the PURG call or sync point processing, whichever comes first. Messages for nonexpress PCBs are sent during sync point processing.

This option is only used by LU 6.2 devices, and it is ignored if specified for a non-LU 6.2 device.

The option is mutually exclusive with the DEALLOCATE_ABEND option. If both options are coded in the options list, an AR status code is returned to the application.

DEALLOCATE_ABEND

deallocates a conversation by issuing a SEND_ERROR followed by a DEALLOCATE_ABEND at the time the message is sent. Once a SETO call with the DEALLOCATE_ABEND option is issued, any subsequent ISRT calls made to the PCB are rejected with a QH status code.

This option is applicable only to LU 6.2 devices. If specified for a non-LU 6.2 device, any subsequent ISRT calls made to the PCB are rejected with a QH status code.

When the SETO call is issued on a TP PCB in an IFP region, the DEALLOCATE_ABEND option is not valid. If you attempt to use the option under these conditions, an AD status code is returned to the application.

The option is mutually exclusive with the SEND_ERROR option. If both options are coded in the options list, an AR status code is returned to the application.

Related reading: For more information about APPC and LU 6.2, see IMS Version 15 Communications and Connections.

Options list feedback area

When errors are encountered in the options list, the options list feedback area is used to return error information to the application.

IMS attempts to parse the entire options list and return information on as many errors as possible. If the feedback area is not large enough to contain all the error information, only as much information is returned as space permits. The status code is the only indication of an option list error if you do not specify the area.

The feedback area must be initialized by the application with a length field indicating the length of the area. A feedback area approximately 1½ to 2 times the length of the options list or a minimum of 8 words should be sufficient.

Error codes

This section contains information on error codes that your application can receive.

Error Code

Reason

(0002)

Unrecognized option keyword.

Possible reasons for this error are:

The keyword is misspelled.
The keyword is spelled correctly but is followed by an invalid delimiter.
The length specified field representing the PRTO is shorter than the actual length of the options.
A keyword is not valid for the indicated call.

(0004)

Either too few or too many characters were specified in the option variable. An option variable following a keyword in the options list for the call is not within the length limits for the option.

(0006)

The length field (LL) in the option variable is too large to be contained in the options list. The options list length field (LL) indicates that the options list ends before the end of the specified option variable.

(0008)

The option variable contains an invalid character or does not begin with an alphabetic character.

(000A)

A required option keyword was not specified.

Possible reasons for this error are:

One or more additional keywords are required because one or more keywords were specified in the options list.
The specified length of the options list is more than zero but the list does not contain any options.

(000C)

The specified combination of option keywords is invalid. Possible causes for this error are:

The keyword is not allowed because of other keywords specified in the options list.
The option keyword is specified more than once.

(000E)

IMS found an error in one or more operands while it was parsing the print data set descriptors. IMS usually uses z/OS services (SJF) to validate the print descriptors (PRTO= option variable). When IMS calls SJF, it requests the same validation as for the TSO OUTDES command. Therefore, IMS is insensitive to changes in output descriptors. Valid descriptors for your system are a function of the MVS release level. For a list of valid descriptors and proper syntax, use the TSO HELP OUTDES command.

IMS must first establish that the format of the PRTO options is in a format that allows the use of SJF services. If it is not, IMS returns the status code AS, the error code (000E), and a descriptive error message. If the error is detected during the SJF process, the error message from SJF will include information of the form (R.C.=xxxx,REAS.=yyyyyyyy), and an error message indicating the error.

The range of some variables is controlled by the initialization parameters. Values for the maximum number of copies, allowable remote destination, classes, and form names are examples of variables influenced by the initialization parameters.

Restrictions

A CPI-C driven application program can issue SETO calls only to an alternate PCB.