Add Object CRQ Activity (ADDOBJCRQA)

The Add Object Change Request Activity (ADDOBJCRQA) command adds an object distribution activity to a change request description. The object referred to in the activity can be an i5/OS object identified by an i5/OS object name or a global name, or a non-i5/OS object such as a PS/2 file which is identified by a global name. The object can also be an installable object which is identified by a global name. An installable object is an object created with more than one i5/OS object.

The activity can be conditioned so that it only runs after one or more other activities have completed (successfully or unsuccessfully). The activity can also be scheduled to run at a future date and time.

Restrictions:

You must have *CHANGE authority to change the request description and *EXECUTE authority to the library.
If a NODL value is specified, the node can only contain entries that have a value of *SNA for the address type.
An object can be specified using an i5/OS object name or a global name but not both.
The global name can be a maximum of 65-n characters in length, where n is the number of tokens. A maximum of 10 tokens can be specified.
The object to be distributed cannot reside in the QTEMP library.

Notes:

The following notes provide information on how the command works.

Authorization to the product specified on the activity is not verified until the activity runs.
All conditions must be satisfied before the activity can run.
The start times indicate when the activity can be started. Actual start times can be later due to network and system delays.
If a global name is used, the Add Distribution Catalog Entry (ADDDSTCLGE) command can be used to indicate where the object is located or stored.
Only i5/OS program objects or file members such as CL and REXX can be run.
The save and restore history for the object is not updated when it is sent or retrieved.
Active message queues are not saved when libraries (*LIB) are sent or retrieved.
Activities are not guaranteed to run in the same jobs. Therefore, references to objects in library QTEMP should be avoided because the scope of QTEMP is only within the job.
If you need to cancel an installation of a NetView Distribution Manager (NetView DM) change file or other non-i5/OS object, you must use the Add Change Management Activity (QNSADDCM) API.

Parameters

Keyword	Description	Choices	Notes
CRQD	Change request description	Qualified object name	Required, Positional 1
	Qualifier 1: Change request description	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
ACTIVITY	Activity	Name, GEN, LAST	Optional, Positional 2
ACTION	Action	SND, RTV, DLT, RUN, SNDRUN, INS, SNDINS, UNINS	Optional
OBJ	Object	Single values: GLOBAL, COMPNAME Other values: Qualified object name	Optional
	Qualifier 1: Object	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
GLBNAME	Global name	Element list	Optional
	Element 1: Global name token 1	Character value, NETID, SERVER, TARGET, MDDATE, *MDTIME
	Element 2: Global name token 2	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 3: Global name token 3	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 4: Global name token 4	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 5: Global name token 5	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 6: Global name token 6	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 7: Global name token 7	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 8: Global name token 8	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 9: Global name token 9	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
	Element 10: Global name token 10	Character value, ANY, HIGHEST, LOWEST, NETID, CPNAME, SERVER, TARGET, MDDATE, *MDTIME
OBJTYPE	Object type	Character value	Optional
MBR	Member	Name, FIRST, LAST, *ALL	Optional
DATATYPE	Data type	UNSPEC, CL, *REXX	Optional
COMPNAME	Component name	Element list	Optional
	Element 1: Component name token 1	Character value, *NETID
	Element 2: Component name token 2	Character value, NETID, CPNAME
	Element 3: Component name token 3	Character value, NETID, CPNAME
	Element 4: Component name token 4	Character value, NETID, CPNAME
	Element 5: Component name token 5	Character value, NETID, CPNAME
	Element 6: Component name token 6	Character value, NETID, CPNAME
	Element 7: Component name token 7	Character value, NETID, CPNAME
REFLVL	Refresh level	Character value, *ALL	Optional
NODL	Managed systems node list	Element list	Optional
	Element 1: Node list	Single values: NONE Other values: Qualified object name*
	Qualifier 1: Node list	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
CPNAME	Managed system node names	Single values: NONE Other values (up to 50 repetitions): Element list*	Optional
	Element 1: Network identifier	Communications name, *NETATR
	Element 2: Control point	Character value
TGTRLS	Target release	CURRENT, PRV, V5R2M0, V5R3M0, V5R4M0	Optional
REPLACE	Replace object	NO, YES	Optional
DTACPR	Data compression	SNA, NONE	Optional
KEEPCLGE	Keep catalog entry	YES, NO	Optional
PARM	Parameters	Values (up to 20 repetitions): Not restricted	Optional
RMTSTRTIME	Start time on managed system	Element list	Optional
	Element 1: Time zone	LCLSYS, MGDSYS
	Element 2: Start after	Element list
	Element 1: Time	Time, *CURRENT
	Element 2: Date	Date, CURRENT, NEXT
TEXT	Text 'description'	Character value, GEN, BLANK	Optional
COND	Activity conditions	Single values: NONE Other values (up to 5 repetitions): Element list*	Optional
	Element 1: Activity	Generic name, name, *PRV
	Element 2: Relational operator	EQ, GT, LT, LE, NE, GE
	Element 3: End code	0-99, SUCCESS, FAIL, NOTRUN, ANY
	Element 4: Condition mode	ALLNODES, SAMENODE
STRTIME	Activity start time	Element list	Optional
	Element 1: Start after	Element list
	Element 1: Time	Time, *CURRENT
	Element 2: Date	Date, CURRENT, NEXT
	Element 2: Start before	Element list
	Element 1: Time	Time, ANY, CURRENT
	Element 2: Date	Date, ANY, CURRENT, *NEXT
HOLD	Hold activity	NO, YES	Optional

Top

Action (ACTION)

Specifies the object distribution function to be performed.

*SND: Sends the specified object to the specified managed system or systems.
*RTV: Retrieves the specified object from the specified managed system or systems. To retrieve an object from more than one system, a global name with an *ANY token is required, so that each retrieved object has a unique global name. Global names with unspecified tokens (*ALL, *HIGHEST, or *LOWEST) are stored in the distribution repository when they are retrieved.
*DLT: Deletes the specified object on the specified system or systems.
*RUN: Runs the specified program on the specified managed system or systems. i5/OS program objects (*PGM), REXX programs or file members containing a CL input stream or a REXX procedure can run on an i5/OS managed system.
*SNDRUN: Sends the specified program and runs it on the specified system or systems. The program that is sent deletes on completion.
*INS: Installs the objects previously packaged for installation on the specified managed system or systems. Only installable objects can be installed.
*SNDINS: Sends the objects previously packaged for installation and install them on the specified managed system or systems. Only objects identified by global names can be installed.
*UNINS: Removes the objects installed on the specified managed system or systems. Only objects installed through an installable object can be uninstalled.

Global name (GLBNAME)

Specifies a global name, which is a series of tokens that uniquely identify an object in an SNA network. The global name represents the name that is used to locate the appropriate catalog entry on both the central site system and the managed systems. The catalog entry specifies the object that is to be used on that system. For example, if a retrieve action is specified, the global name is used to determine the object that is to be retrieved on the managed system. Also, the global name shows the location where it is to be stored on the central site system.

Special values in a token position indicate how to search for the object. By specifying *ANY in a token position, the token is ignored when searching for the correct object. If multiple objects are found matching the tokens specified, an error is returned.

If an object is sent, the global name must have been previously cataloged so that it is associated with a local object name or associated with an object in the distribution repository. Retrieved objects, for which no catalog entry exists, are placed in the distribution repository. The GLBNAME parameter cannot be specified if the object name is not *GLOBAL.

The GLBNAME parameter is not valid when the ACTION value is *UNINS. When the OBJ is *GLOBAL and the global name maps to an installable object, the global name must have the following structure.

ComponentName REF RefreshLevel

In this example,

Component names are the tokens before the token with the REF value. It is used to distinguish objects of an installable object from those from another. The component can be between 1 and 7 tokens.
The REF token is required to identify the global name as an installable object. It can only be specified from token 2 through 8 in the global name.
The refresh level is a token with a numeric value. The refresh level shows the level of the installable object and must follow the token with the REF value.

Token 1: Element 1

*NETID: The first global name token value is a network ID generated by the command from the network attributes. The network ID is determined by the current value of the LCLNETID network attribute value.
*SERVER: This token is stored within the change request activity with the value &SERVER, and is replaced by the short name of the change control server when the object is distributed.
*TARGET: This token is stored within the change request activity with the value &TARGET, and is replaced by the short name of the target when the object is distributed.
*MDDATE: This token is stored within the change request activity with the value &DATE, and is replaced when distributed by the date the object was last modified.
*MDTIME: This token is stored within the change request activity with the value &TIME, and is replaced when distributed by the time the object was last modified.
global-name-token: Specify the first token of the global name. The first token is recommended to be the registered enterprise ID or network ID.

Tokens 2-10: Elements 2-10

*ANY: Any token value matches when searching for the object where the action is to be performed. This is useful when retrieving objects for which some of the tokens in the global name are not known or vary between systems.
*HIGHEST: The object with the highest token value has the action performed on it. The token must be ordered. This is useful when a token in a global name is used to indicate a different version of the object and you need to manipulate the object with the highest version level.
*LOWEST: The object with the lowest token value has the action performed on it. The token must be ordered. This is useful when a token in a global name is used to indicate a different version of the object and you need to manipulate the object with the lowest version level.
*NETID: The network ID of this system is used. The network ID is determined by the current value of the LCLNETID network attribute value.
*CPNAME: The control point name of this system is used. The control point name is determined by the current value of the LCLCPNAME network attribute value.
*SERVER: This token is stored within the change request activity with the value &SERVER, and is replaced by the short name of the change control server when the object is distributed.
*TARGET: This token is stored within the change request activity with the value &TARGET, and is replaced by the short name of the target when the object is distributed.
*MDDATE: This token is stored within the change request activity with the value &DATE, and is replaced when distributed by the date the object was last modified.
*MDTIME: This token is stored within the change request activity with the value &TIME, and is replaced when distributed by the time the object was last modified.
Note: For more detailed information about the Change Control Server support see the Managed System Services for iSeries Use book.
global-name-token: Specify one of a series of 1 to 16-character tokens that uniquely identify the object on which the action is to be performed. Characters A through Z and 0 through 9 can be used. Other special values (@, #, and $) can be used for tokens that represent network IDs and system names.

Component name (COMPNAME)

Component name, which is the set of tokens of a global name previous to the REF token. The component name is used to identify the installable objects that will be uninstalled. The component name is only valid when ACTION(*UNINS) and OBJ(*COMPNAME) are specified.

Element 1: Token 1

The only special value allowed for the first token is *NETID.

*NETID: The network ID of this system is used. The network ID is determined by the current value of the LCLNETID network attribute value.
component-name-token: One of a series of 1 to 16 character tokens that uniquely identifies the object on which the action is to be performed. Characters A through Z and 0 through 9 can be used. Other special values (@, #, and $) can be used for tokens that represent network IDs and system names.

Elements 2-7: Tokens 2-7

*NETID: The network ID of this system is used. The network ID is determined by the current value of the LCLNETID network attribute value.
*CPNAME: The control point name of this system is used. The network ID is determined by the current value of the LCLCPNAME network attribute value.
component-name-token: One of a series of 1 to 16 character tokens that uniquely identifies the object on which the action is to be performed. Characters A through Z and 0 through 9 can be used. Other special values (@, #, and $) can be used for tokens that represent network IDs and system names.

Managed system node names (CPNAME)

Specifies the APPN control point names of the managed systems on which this activity is to be performed. Control point names cannot be specified if a node list is specified.

The possible value is:

*NONE: The systems on which this activity is to be performed are not identified individually. A node list must be specified.

The possible value is:

*NETATR: The network ID of the local system is used. This is useful when the node being specified is in the same network as the local system.
network-identifier: Specify the APPN network identifier of the managed system on which the activity is to be performed.

The possible control point name value is:

control-point-name: Specify the APPN control point name of the managed system on which the activity is to be performed. For NetView Distribution Management Agents, the control point name is the change control client which supports numeric characters (0-9) in the first position of control point names that are valid in other platforms.

Target release (TGTRLS)

Specifies the release of the operating system on which you intend to use the object. This parameter is ignored for objects with global names that are in the SystemView distribution repository or for actions other than send or retrieve.

*CURRENT: The object is used on the release of the operating system currently running on your system. If V5R4M0 is running on your system, *CURRENT means that you intend to use the object on a system with V5R4M0 installed. The object can also be used on a system with any later release of the operating system installed.
*PRV: The object is intended for a system which is at the previous release level compared to the local system.
Note: Modification levels are not supported. To specify a previous release with a modification level other than 0, such as V5R3M4, specify the value for the release rather than the special value of *PRV.
release-level: Specify the release level in the VxRxMx format. The object is used on a system with the specified release or with any later release of the operating system installed.
Valid values depend on the current version, release, and modification level, and they change with each new release.

Start time on managed system (RMTSTRTIME)

Specifies the date and time when the activity can begin running on the managed system. The current date and time values and next date values are determined when the activity begins running at the central site system based on the central site date and time.

The possible values of the time zone of the remote start time are:

*LCLSYS: The remote start time is specified in the time zone of the central site system.
*MGDSYS: The remote start time is specified in the time zone of the managed system.

The possible start after time values are:

This is the definition of the time after which the activity is to start.

*CURRENT: This function can start on the managed system at any time on or after the time this activity is started on the central site system on the date specified in element 2.
start-after-time: Specify the time when this function can start on the managed system. The time can be entered as 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds. Seconds are optional. The time can be specified with or without a time separator. With a time separator, specify a string of 5 or 8 digits such as hh:mm:ss.

The possible start after date values are:

*CURRENT: This function starts on the managed system on any date on or after the activity starts on the central site system.
*NEXT: This function starts on the managed system on any date after the activity starts on the central site.
start-after-date: Specify the date after the functions start on the managed system. The date must be specified in the job date format.

Notes:

The special values *CURRENT and *NEXT are specified for the date and the time if the time zone value *MGDSYS is specified.
This parameter can only be specified if *RUN, *SNDRUN, *INS, *SNDINS, and *UNINS actions are specified.

Activity conditions (COND)

Specifies which conditions must be met before this activity can be performed. Each condition identifies an activity which must run before this activity, and the value the end code from that activity must have to allow this activity to run. The default condition is that the previous activity (in alphabetical order) must complete successfully before this activity can be run.

The possible single value is:

*NONE: There are no conditions for this activity.

The possible conditioning activity values are:

These are the activities which must be run before this activity.

*PRV: This activity is conditioned on the previous activity. Activities are ordered alphabetically by activity name. If the activity being added is the first activity, a previous activity does not exist and any condition with *PRV is marked as having been met.
conditioning-activity-name: Specify the name of the activity which must run before this activity. The activity name specified in the activity (ACTIVITY) parameter cannot be specified in the conditioning activity name. An activity cannot be conditioned on itself.
generic*-activity-name: Specify the generic name of the activities which must run before this activity.

The possible relational operator values are:

This element is the relational operator to use when comparing the end code from the conditioning activity.

*EQ: Equal
*GT: Greater than
*LT: Less than
*NE: Not equal
*GE: Greater than or equal
*LE: Less than or equal

The possible condition code values are:

This element is the value compared to the actual end code of the conditioning activity.

*SUCCESS

The activity ended successfully (0 <= end code <= 9). This end code can only be specified with relational operator *EQ or *NE.

*FAIL

The activity failed (10 <= end code <= 89). This end code can only be specified with relational operator *EQ or *NE.

*NOTRUN

The activity is never started (90 <= end code <= 99). This end code is only specified with relational operator *EQ or *NE.

*ANY

The activity ended with any end code. This end code is only specified with relational operator *EQ.

end-code

Specify an integer value (0-99) that indicates the result of an activity (success or failure). The end code ranges and descriptions are:

00

Activity completed successfully.

01-09

Activity completed with warning messages.

10-29

Activity did not complete successfully.

30-39

Activity was canceled by a user before it completed.

30 = Activity ended with *CNTRLD option
35 = Activity ended with *IMMED option
39 = Activity ended with *FRCFAIL option

40-49

Activity was not run due to errors detected by the application.

40 = Activity not run for security reasons

90-99

Activity was not run because conditions or schedules were not met.

95 = Scheduled start time expired
99 = Conditions cannot be met

The possible condition mode values are:

This element indicates which systems the conditioning activity must have completed on before this activity can be performed.

*ALLNODES: The conditioning activity specified must complete on all nodes before this activity runs.
*SAMENODE: When the conditioning activity specified completes for a given node, the activity specified on the ACTIVITY parameter may run for that same node even though the conditioning activity specified may not have completed for all other nodes. In the case where this activity lists a node not in the conditioning activity, this activity may run for that node; the condition is ignored.

Activity start time (STRTIME)

Specifies the date and time when this activity can be started on the central site system. The current date and time values, and next date values are determined when the change request is submitted.

The possible start after time values are:

*CURRENT: This activity can start any time on or after the time when the change request is submitted.
start-after-time: Specify the time when this activity can start. The time can be entered as 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds. Seconds are optional. The time can be specified with or without a time separator such as a colon (:). With a time separator, specify a string of 5 or 8 digits such as hh:mm:ss.

The possible start after date values are:

*CURRENT: This activity can start on or after the date on which the change request is submitted.
*NEXT: The activity can start on any date after the date when the change request is submitted.
start-after-date: Specify the date after this activity can start. The date must be specified in the job date format.

The possible start before time values are:

This element is ignored if the start before date is *ANY.

*ANY: The activity can start at any time on or before the start before date.
*CURRENT: The activity must start before the time when the change request was submitted on the date specified on the start before data element.
start-before-time: Specify the time before the activity must start. If the activity cannot be started before this time, it never starts. The time can be entered as 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds. Seconds are optional. The time can be specified with or without a time separator such as a colon (:). With a time separator, specify a string of 5 or 8 digits (hh:mm or hh:mm:ss).

The possible start before date values are:

*ANY: The activity can start at any time after the start after time and the start after date.
*CURRENT: The activity must start on the date the change request is submitted.
*NEXT: The activity must start by the day after the date the change request is submitted.
start-before-date: Specify the date before the activity must start. If the activity cannot start by this date, it never starts. The date must be specified in the job date format.

Examples

Example 1: Adding an Activity to a Change Request Description

ADDOBJCRQA   CRQD(MYLIB/CR1)  ACTIVITY(ACT01)   ACTION(*RTV)
             OBJ(QGPL/QXYZ)  OBJTYPE(*JOBD)
             CPNAME((*NETATR SYS1))

This example shows how to add an activity to change request description CR1 in library MYLIB which retrieves the QGPL/QXYZ job description from the iSeries server SYS1 in the local network.

Example 2: Adding an Activity to an Accounting System

ADDOBJCRQA   CRQD(MYLIB/CR2)  ACTIVITY(ACT02)  ACTION(*SND)
             OBJ(ACCTLIB/TAXFILE)  OBJTYPE(*FILE)
             MBR(DEDUCTIONS)  TGTRLS(*PRV)
             STRTIME((23:00:00 9/30/02))
             NODL(NETLIB/ACCTSYS)

This example shows how to add an activity to send a tax table to all of the iSeries accounting servers in the ACCTSYS node list at 11 p.m. on 30 September 2002. The accounting systems are at the previous release level.

Example 3: Adding an Activity to Retrieve a Program

ADDOBJCRQA   CRQD(MYLIB/CR3)  ACTIVITY(*GEN)  ACTION(*RTV)
             OBJ(*GLOBAL)
             GLBNAME(CUSTNET PCSOFT WDWAPP VER5 020314)
             CPNAME((CUSTNET DEVPS2))

ADDOBJCRQA   CRQD(MYLIB/CR3)  ACTIVITY(*GEN)  ACTION(*SND)
             OBJ(*GLOBAL)
             GLBNAME(CUSTNET PCSOFT WDWAPP VER5 020314)
             NODL(NETLIB/PS2SE)

ADDOBJCRQA   CRQD(MYLIB/CR3)  ACTIVITY(*GEN)  ACTION(*RUN)
             OBJ(*GLOBAL)
             GLBNAME(CUSTNET PCSOFT WDWAPP VER5 020314)
             COND((*PRV *EQ *SUCCESS *SAMENODE))
             RMTSTRTIME((*MGDSYS (23:00:00 10/20/02))
             NODL(NETLIB/PS2SE)

This command adds activities to retrieve a program from a PS/2, and sends it to all of the PS/2s in the southeast area. The PS/2s are identified in the PS2SE node list. It runs it on the PS/2s at 11 p.m. in the time zone where the PS/2 is located only if the send to the PS/2 was successful. The activity names are generated.

Example 4: Adding an Activity to Retrieve a File from Multiple Systems

ADDOBJCRQA   CRQD(MYLIB/CR4)  ACTIVITY(ONLY)  ACTION(*RTV)
             OBJ(*GLOBAL)  GLBNAME(CUSTNET SALES *ANY *HIGHEST)
             STRTIME((22:00:00 *CURRENT) (06:00:00 *NEXT))
             NODL(NETLIB/STORES)

This command adds an activity to retrieve the most recent nightly sales file from each system identified in the STORES node list. The files are cataloged as CUSTNET SALES system-name date-created. The file must be retrieved after 10 p.m. on the day the request is submitted but before 6 a.m. the next morning when the stores open.

Example 5: Adding an Activity to Send an Installable Object

ADDOBJCRQA   CRQD(MYLIB/CR1)  ACTIVITY(01)  ACTION(*SND)
             OBJ(*GLOBAL)
             GLBNAME(CUSTNET ASOBJ PCKOBJ 01269 REF 0001)
             CPNAME((*NETATR SYS1))

This command adds an activity to send an object that was previously packaged for installation in the central site to the iSeries server SYS1.

Example 6: Adding an Activity to Send and Install an Installable Object

ADDOBJCRQA   CRQD(MYLIB/CR2)  ACTIVITY(ACT02)  ACTION(*SNDINS)
             OBJ(*GLOBAL)
             GLBNAME(CUSTNET ASOBJ PCKOBJ 01270 REF 0002)
             NODL(NETLIB/ACCTSYS)  KEEPCLGE(*NO)

This command adds an activity to send and install an installable object that was previously packaged for installation to the node list ACCTSYS. The catalog entry in the managed system pointing to the installable object is not kept.

Example 7: Uninstalling an Installable Object

ADDOBJCRQA   CRQD(MYLIB/CR4)  ACTIVITY(ACT04)  ACTION(*UNINS)
             OBJ(*COMPNAME)
             COMPNAME(CUSTNET ASOBJ PCKOBJ 03000)
             REFLVL(*ALL)  CPNAME(*NETATR SYS4)

This command adds an activity to uninstall all the installable objects from the system SYS4 whose global name matches the component name CUSTNET ASOBJ PCKOBJ 03000, no matter what release level it has.