ALTERW: Alter workmod

ALTERW allows you to change or delete symbols, control sections, or common areas and lengthen sections in a program module. The value specified on the MODE parameter determines whether the request is performed on all items currently in the workmod, or delayed to be performed only on the next program module included in the workmod.

The ALTERW request with MODE=NEXT should be followed by an include request for an object module or program module. If it is not, any pending alterations for the next included data set are ignored.

The syntax of the ALTERW call is:

[symbol]

IEWBIND

FUNC=ALTERW

[,VERSION=version]
[,RETCODE=retcode]
[,RSNCODE=rsncode]
,WORKMOD=workmod
,ATYPE={CHANGE | DELETE | EXPAND |
REPLACE}
[,MODE={IMMED | NEXT}]
,OLDNAME=oldname
[,NEWNAME=newname]
[,COUNT=count]
[,CLASS=class]

FUNC=ALTERW

Specifies that you are changing or deleting a symbol or control section or lengthening a section within the 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 ALTERW call, CLASS cannot be specified as a macro keyword. The parameter list ends with the COUNT 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 returned on the CREATEW request.

ATYPE={CHANGE | DELETE | EXPAND | REPLACE}

Specifies the type of alteration that is made on the designated workmod. The value for ATYPE can be abbreviated as: C, D, E, or R.

The alteration is performed either on the next module included in the workmod or on all modules currently in the workmod, depending on the argument specified on the MODE parameter. The possible arguments are as follows:

CHANGE: Changes an external symbol of any ESD type from OLDNAME to NEWNAME. The symbol is changed in the target module(s). Occurrences of the symbol in other modules, other workmods, or in directory entries are not affected.
If NEWNAME is already a defined symbol in the workmod, the existing NEWNAME is deleted when this function begins processing. A warning message is issued. Note that the results of the CHANGE operation can differ from those of the linkage editor in this situation,
DELETE: Deletes an external symbol in the target module(s). If you specify an entry name, the symbol definition is removed from the ESD and symbol references are unaffected. If you specify a control section or common section name, any items in the workmod with that section name are deleted. any external references in the workmod to the deleted symbol are unresolved.
EXPAND: Expands the length of the text of a section. The COUNT parameter is required and indicates the amount by which the section should be expanded. The same rules that apply to usage of the EXPAND control statement are in effect; see the EXPAND statement in z/OS MVS Program Management: User's Guide and Reference for more information.
REPLACE: Allows you to delete a symbol (OLDNAME) and change any references to that symbol to a new name (NEWNAME). If you specify a symbol that refers to a section, all items having that name are deleted from the workmod. If you specify a symbol, this operation is the same as the CHANGE alteration. Any external references to the deleted section within the workmod are changed to the new name.

MODE={IMMED | NEXT}

Specifies when the operation is to take place. The values are as follows:

IMMED: The operation is to take place on all modules currently in the workmod.
NEXT: The operation is to take place on the next module included in the workmod. This value is the default.

The value for MODE can be abbreviated as I or N.

OLDNAME=oldname — RX-type address or register (2-12)

Specifies the location of a varying character string that contains the section name or symbol to be changed, deleted, or replaced, or the name of the section to be expanded. If OLDNAME is left blank, it is assumed to be a reference to a blank common section. The maximum length of OLDNAME is 32767 bytes.

NEWNAME=newname — RX-type address or register (2-12)

Specifies the location of a varying character string that contains the new symbol name for a change or replace operation. NEWNAME must not contain all blanks. The maximum length of NEWNAME is 32767 bytes.

COUNT=count — RX-type address or register (2-12)

Specifies the location of a fullword that contains the number of bytes by which to lengthen a section for an expand operation.

CLASS=class — RX-type address or register (2-12)

Specifies the name of a 16-byte varying character string variable containing the class name of the item to be EXPANDed. If you specified anything other than EXPAND for the ATYPE parameter, this parameter is ignored. If CLASS is not specified, the default is B_TEXT.

Processing notes

An ALTERW request is valid only when the processing intent is BIND.

NEWNAME is required for change and replace alterations. It is ignored on delete and expand alterations.

The scope of the requested operation is the designated workmod or the next module to be included into the workmod by the binder, regardless of its source. An included module refers to the next object or program module to enter the designated workmod; the first END record (object module) or end-of-module indication (program module) delimits the scope of ALTERW. Alter Workmod does not affect any module(s) residing in other workmods or that enter the workmod following the target module.

If an ALTERW request is not followed by an INCLUDE, such that a BINDW, LOADW or SAVEW request is received and alterations are pending, the alterations are not applied to the first autocalled module but are ignored. Similarly, if one or more alterations are pending as a result of a CHANGE or REPLACE control statement encountered in an autocalled member and an end-of-file is encountered, those alterations are not applied to the next autocalled member.

ALTERW has no effect on symbols or section names appearing in previous or subsequent deferred function requests, such as ADDA, ALIGNT, INSERTS, ORDERS, or SETL.

Return and reason codes

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

Return Code	Reason Code	Explanation
00	00000000	Normal completion. Module altered or deferred request accepted.
04	83000702	OLDNAME not found. For an immediate-mode change or replace request, no ESD entries in the module contained the specified name.
04	83000706	Duplicate name. For an immediate mode request, the replacement name already exists as an external symbol in the target workmod. The old name or section will be deleted if necessary, and the requested change will be made.
08	83000550	A section for which an expand request was made is not in the target workmod. Workmod is unchanged.
08	83000551	The name on an expand request matched a symbol in workmod that was not a section name. Workmod is unchanged.
08	83000552	The name on a change or replace request is blank. Workmod is unchanged.
08	83000553	Expand request for more than 1 gigabytes was made. Workmod is unchanged.
08	83000554	The class name specified or defaulted does not exist in the section you specified. The element cannot be expanded. Workmod is unchanged.
08	83000555	Designated class is not a text class. The element cannot be expanded. Workmod is unchanged.
12	83000104	INTENT=ACCESS specified for workmod. Module could not be altered.

Parameter list

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

Table 1. ALTERW parameter list

`PARMLIST`	`DS`	`0F`
	`DC`	`A(ALTERW)`	Function code
	`DC`	`A(RETCODE)`	Return code
	`DC`	`A(RSNCODE)`	Reason code
	`DC`	`A(WORKMOD)`	Workmod token
	`DC`	`A(ATYPE)`	Alter type
	`DC`	`A(MODE)`	Alter mode
	`DC`	`A(OLDNAME)`	Old name
	`DC`	`A(NEWNAME)`	New name
	`DC`	`A(COUNT)`	Number of bytes
	`DC`	`A(CLASS)`	Class
`ALTERW`	`DC`	`H'50'`	ALTERW function code
	`DC`	`H'version'`	Interface version number
`ATYPE`	`DC`	`C'C'`	Alter type: 'C' = Change 'D' = Delete 'E' = Expand 'R' = Replace
`MODE`	`DC`	`C'N'`	Alter mode: 'I' = Immediate 'N' = Next

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