CHNG call

The Change (CHNG) call sets the destination of a modifiable alternate PCB to the logical terminal, LU 6.2 descriptor, or transaction code that you specify. You can also use the CHNG call with the Spool Application Program Interface (Spool API) to specify print data set characteristics.

Format

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

Parameters

alternate pcb

Specifies the modifiable alternate PCB to use for this call. This parameter is an input and output parameter.

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 name of a modifiable alternate PCB.
AIBOALEN: I/O area length. This field must contain the length of the I/O area that is specified in the call list.

destination name

Specifies an 8-byte field containing the destination name (the logical terminal or transaction code) to which you want messages sent. This parameter is an input parameter. The destination name can be up to 8 bytes. When you specify LU 6.2 options, IMS TM sets the destination name in the alternate PCB to DFSLU62b. If an LU 6.2 options list is specified the destination name parameter is ignored.

For more information on LU 6.2, see IMS Version 15.5 Communications and Connections.

The destination name may also be used to implement message switches from OTMA to non-OTMA destinations. In this case, the destination name must match the name of the routing descriptor in the DFSYDTx member of IMS.PROCLIB.

Restriction: Some destination names are invalid. For more information on resource naming rules, see IMS Version 15.5 Communications and Connections.

options list

Specifies one of several option keywords. This parameter is an input parameter. 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.

For more information on APPC, see IMS Version 15.5 Communications and Connections.

The format for the options list is shown here:

LL or LLLL ^{1, 2, 3}	ZZ	keyword1=variable1
Halfword length of the options string, including the 4-byte length of LLZZ or LLLLZZ.	Halfword of zero.	CHNG options separated by commas.
Notes: 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 options list is ignored. IMS TM processes the CHNG call as if the `options list` parameter was not specified. A keyword must be separated from the following variable by an equal sign (=). A keyword with no variable must be delimited by a comma or blank.

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 error. 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 following table shows the format for the feedback area passed to IMS in the call list:

LL or LLLL ^1, 2	ZZ
Halfword length of the feedback area, including the 4-byte length of the LLZZ fields.	Halfword of zero.
Notes: 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 feedback area is ignored. IMS TM processes the CHNG call as if the feedback area parameter was not specified.

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

LLZZ or LLLLZZ	LL	feedback data
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

Use the CHNG call to send an output message to an alternate destination in your system or in another system. When you issue the CHNG call, you supply the name of the destination to which you want to send the message. The alternate PCB you name then remains set to that destination until you do one of the following:

Issue another CHNG call to reset the destination.
Issue a Get Unique (GU) call to the message queue to start processing a new message. In this case, the name of the PCB you specify with the CHNG call still appears in the alternate PCB, even though it is no longer valid.
Terminate the application program. When you terminate the application, IMS TM resets the destination to blanks.

You can use the CHNG call to perform Spool API functions.

For Spool API functions, each CHNG call to a nonexpress, alternate PCB, creates a separate JES spool data set. (PURG calls have no effect when issued against a nonexpress, alternate PCB.) If the destination of the PCB is the JES spool, it cannot be CHNGed to a non-JES spool destination until the data set(s) have been released by a sync point. Keywords that can be specified on the CHNG call are discussed below.

In the OTMA environment

If an IMS application program issues a CHNG call to an alternate PCB and specifies an options list, then the output destination cannot be an IMS Open Transaction Manager client.

An IMS application program that issues a CHNG call to an alternate PCB (specifying an options list) does not cause IMS to call the OTMA Prerouting and Destination Resolution exit routines to determine the destination. But an IMS application program that issues a CHNG call to an alternate PCB (specifying an APPC descriptor) does cause IMS to call the OTMA exit routines to determine the destination. For information on these exit routines, see IMS Version 15.5 Exit Routines.

The application program can still issue ISRT calls to the I/O PCB to send data to an OTMA destination.

OTMA application programs can use CHNG and ISRT calls for APPC destinations. For more information, see IMS Version 15.5 Communications and Connections.

Advanced print function options

The IAFP keyword identifies the CHNG call as a request for Spool API functions. The parameters of the IAFP keyword are:

Keyword: Description
IAFP=abc: a — specifies carriage control options
: b — specifies integrity options
: c — specifies message processing options

These options specify advanced print functions for the CHNG call.

Carriage control options: The 1-character carriage control options indicate the type of carriage control that is present in the message data when the ISRT or PURG call is issued. Your application program must insert the proper carriage control characters in the data stream. You can specify one of the following values for the IAFP keyword:

A: The data stream contains ASA carriage control characters.
M: The data stream contains machine carriage control characters.
N: The data stream does not contain carriage control characters.

Integrity options: The 1-character integrity options indicate the method IMS TM uses in allocating the IMS Spool data set that contains the IAFP message. You can specify one of the following options for the IAFP keyword:

0: IMS TM attempts no data set protection. Your application program must provide any disposition or hold status by using the appropriate OUTPUT descriptor options. IMS TM does attempt to prevent a partial message from printing and to deallocate data sets that contain messages that have already reached a sync point. To control whether error messages about the IMS Spool data set are issued, use the message processing options for the IAFP keyword.
1: The IMS Spool data set is placed on the SYSOUT HOLD queue when it is allocated. If IMS TM issues message DFS00121 or DFS00141, the operator must query the SYSOUT HOLD queue to locate the appropriate data sets. IMS TM releases the data set and deallocates it to be printed at sync point.
When you specify 1 for the integrity option, you must specify M for the message processing option of the IAFP keyword.
2: A remote destination is specified in the destination name parameter on the CHNG call. The IMS Spool data set, when allocated, is placed on a SYSOUT remote workstation, IMSTEMP. This destination must be included in the definitions as nonselectable so that the data set is not automatically selected to be printed. If IMS TM issues message DFS00121 or DFS00141, the operator must query IMSTEMP to locate the appropriate data sets. At sync point, IMS TM releases the data set and deallocates it to the remote workstation ID specified in the destination name parameter. The value 2 overrides any destination specified in the IAFP OUTPUT options.

Message processing options: The 1-character message processing options indicate whether IMS TM issues message DFS00141 during restart and message DFS00121 for dynamic allocation failures. You can specify one of the following options:

0: DFS00121 and DFS00141 are not issued. Your application program controls IAFP message integrity.
M: DFS00121 and DFS00141 are issued if necessary. IMS TM controls IAFP message integrity.

The CHNG call can provide the data set characteristics by:

Directly, using the PRTO= option
Referencing prebuilt text units, using the TXTU= option
Referencing an OUTPUT JCL statement in the dependent region's JCL, using the OUTN= option

When you use the IAFP keyword, you must also specify the PRTO, TXTU, or OUTN option. (The options PRTO, TXTU, and OUTN are mutually exclusive.) If you do not specify one of these additional options, or if you specify more than one of these options, or if you specify IAFP with an invalid value, IMS TM returns an AR status code to your application program.

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.
Note: Some options depend on the release level of MVS.

TXTU=address: specifies the address of a list of text-unit pointers. The list (with the associated text units) can be created by a previous SETO call, or it can be created by your application program. The LLZZ or LLLLZZ prefix must be included on the buffer that contains the list. TXTU allows your application program to issue a SETO call to build the text units for the OUTDES options before the CHNG call is issued.
If your application program issues several CHNG calls with the same OUTDES printer options, the TXTU option means you do not need to build OUTDES options for each CHNG call.
OUTN=name: specifies a character string up to eight characters long that contains the name of an OUTPUT JCL statement that identifies the printer processing options to be used. If the specified OUTPUT DD statement is not included in the JCL for the region in which the application program runs, a dynamic allocation error occurs when the application attempts to insert data to the data set.

APPC options: The following APPC options are available for the CHNG call:

Keyword

Description

LU=logical unit name

Specifies the logical unit (LU) name of a partner for an LU 6.2 conversation with a partner application program. It is used in conjunction with the MODE and TPN options to establish the conversation. The LU name can be any alphanumeric string including national characters, but the first character cannot be a number. If the LU name is a network-qualified name, it can be up to seventeen characters long and consist of the network ID of the originating system, followed by '.', then the LU name. (for example, netwrkid.luname). The LU name and the network ID are both one to eight characters long. The default for this option is DFSLU.

MODE=mode name

Specifies the mode of the partner for an LU 6.2 conversation with a partner application program. It is used in conjunction with the LU and TPN options to establish the conversation. The mode name can be any alphanumeric string up to eight characters long, including national characters, but the first character cannot be a number. If both MODE and SIDE options are specified, the mode name specified in the SIDE entry is ignored but is not changed. The default for this option is DFSMODE.

TPN=transaction program name

Specifies the transaction program (TP) name of the partner application program in an LU 6.2 conversation. The option is used in conjunction with the LU and MODE keywords to establish the conversation.

TP names can be up to 64 characters long and can contain any character from the 00640 character set except a blank. The 00640 character set includes the letters A-Z, the digits 0-9, and 20 special characters. The default for this option is DFSASYNC. For more information on the 00640 character set, see CPI Communications Reference. The format for the TPN option is as follows:

LL	tpn
Halfword length of the TP name, including the 2-byte length of LL.	The TP name, which can be up to 64 characters long.

TP names that are processed with the IMS command processor must contain characters that are valid to IMS. For example, names that contain lower case letters cannot be processed and are rejected if they are used as operands for IMS commands.

SIDE=side information entry name

Specifies the side information entry name that can be used to establish an LU 6.2 conversation with a partner application program. The SIDE name can contain up to eight characters, including the uppercase alphabet (A-Z), and the digits 0-9. If the LU, MODE, or TPN keywords are specified, they override the SIDE keyword, but they do not change the side information entry name. This option has no default.

SYNC=NC

Overrides the APPC/IMS conversation synchronization level. N sets the synchronization level to NONE. C sets the synchronization level to CONFIRM. The default for this option is C.

TYPE=BM

Overrides the APPC/IMS conversation type. B sets the conversation type to BASIC. M sets the conversation type to MAPPED. The default for this option is M.

Related reading: For more information on APPC and the default options, see IMS Version 15.5 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.5 to 2 times the length of the options list or a minimum of 8 words should be sufficient.

Error codes

This topic 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

Before you can use the CHNG call to set or alter the destination of an alternate PCB, you must issue the PURG call to indicate to IMS that the message that you have been building with that PCB is finished.

LU 6.2 architecture prohibits the use of the ALTRESP PCB on a CHNG call in an LU 6.2 conversation. The LU 6.2 conversation can only be associated with the IOPCB. The application sends a message on the existing LU 6.2 conversation (synchronous) or has IMS create a new conversation (asynchronous) using the IOPCB. Since there is no LTERM associated with an LU 6.2 conversation, only the IOPCB represents the original LU 6.2 conversation.