MDADDREQ - Generate Object Request Records command

MDCMS is delivered with a command-based API that allows external tools or applications to create Object Requests within MDCMS.

The MDCMS command is named MDADDREQ and is located in library MDCMS. It is not necessary to have the MD libraries in the library list prior to using this command. If you are unable to invoke a command from your tool, you can also directly call program MDADDREQ in library MDCMS. In this case, be certain that the parameter order and formats sent to the program exactly match the parameters in command MDADDREQ.

All MDADDREQ API transactions are logged to file MDCMS/MDDAREQ.

MDADDREQ Parameter Table

Detailed Description of MDADDREQ Parameters

Application (APPL)

The target MDCMS Application code for the request

This is a required parameter.

Level (LVL)

The target MDCMS Promotion Level for the request that allows check-outs

This is a required parameter.

Object Type (OBJT)

The System or MDCMS Object Type code for the Object. For example: *PGM for a program or *IFS for an IFS file.

This is a required parameter.

MDCMS Attribute (ATTR)

The MDCMS Attribute code that identifies the behaviour and target locations for the requested object.

This is a required parameter.

Object Name (OBJN)

The name of the Object to be requested.

For *SOURCE, this would be the name of the member

For *MSGD, this would be the name of the Message ID

For *DTAGRP, this would be the value of the record key(s)

This is a required parameter.

Relative Path (RPTH)

Specifies the relative portion of an IFS path, starting with /, that will be deployed with the object.

For example, if the *IFS attribute has a target fixed directory defined as /srv/dev and this object should be deployed to /srv/dev/app1/dist, then the value of RPTH should be /app1/dist.

Member/IFS File Name (SRCN)

Specifies the name of the Source Member or IFS Source File to be requested. This parameter is ignored if attribute defined as having no source.

*OBJ - The name of the source is the same as the name of the object

Request Reason (RSN)

The reason for the object request

*MIGRATE - a source and/or object will be migrated into the selected application level

*DELETE - an existing object will be deleted

*RECOMPILE - an object will be recompiled based on the currently active source for that environment without the source being modified

*UPDATE - this is intended for ILE programs to bind the current modules and service programs to the program. A U command (such as CHGPGM) must be defined for the attribute.

Programmer (USER)

Specifies the user profile to be indicated as the programmer for the request. If this command generates an RFP, the owner of the RFP will also be this user

*USER - the current user profile of the job invoking this command is the user

From Object Library/Path (FOLB)

Specifies the library or IFS path that contains the object to be migrated to the specified level. The library should be a developer or team library that is not managed by MDCMS.

If the attribute contains source only, then enter the library/path containing the source.

If the object resides in IFS, provide the entire directory path starting with /.

*USER - the library name is the same as the user defined for parameter USER

From Source Library/Path (FSLB)

Specifies the library or IFS path that contains the source for the object that is to be migrated to the specified level. The library should be a developer or team library that is not managed by MDCMS. This parameter is ignored if attribute is defined as having no source.

*OBJLIB - the library containing the source is the same library that contains the object

From Source File (FSFL)

Specifies the source file containing the source member to be migrated. This parameter is ignored if attribute defined as having no source.

*ATR - the Source File to migrate from has the same name as the source file defined for the attribute.

Copy Source/Object from Env (COPY)

Specifies if the source or object should be copied from the target environment to the library from which to be migrated from. This parameter is only considered for Reason *MIGRATE.

If the attribute defines a source and object location, only the source will be copied.

If the source or object already exists in the From Library, it will not be replaced by the source or object in the target environment.

*NO - the Source or Object will be manually placed in the From Library prior to migration.

*YES - MDCMS will copy the Source or Object from the Target Environment to the From Library, if it doesn't already exist in the From Library.

Project (PROJ)

Specifies the Project to assign to the Request. The project, if entered, must already exist and be in an open status. If the project is not yet authorized, then the user must have MDSEC authority to authorize the Project and then MDCMS will do so automatically.

Task (TASK)

Specifies the Project Task to attribute to the Request. The task, if entered, must already exist and be in an open status.

Subtask (STSK)

Specifies the Subtask to attribute to the Request. The Subtask, if entered, must already exist and be in an open status.

Assign Request to RFP (ARFP)

Specifies if the request should be immediately assigned to an RFP and the method of determining the RFP.

*NO - The request will be created without being assigned to an RFP

*YES - The request will be assigned to the RFP number based on parameter RFP

*AUTO - MDCMS searches for an open RFP matching the Application, Level, User and Description values entered for this command. If an RFP is found the Request will be assigned to that RFP. If an RFP is not found, a new RFP will be created.

*NEW - A new RFP will be created for the Application, Level, User and Description values entered for this command.

Existing RFP Number (RFP)

Specifies the RFP to assign to the Request. Will only be used if parameter ARFP is set to *YES.

RFP Description (RFPD)

The description to be used for a new RFP or to search for an existing RFP. Will only be used if parameter ARFP is *AUTO or *NEW.

Create Requests for Next Level (CREQ)

If a level exists to migrate after this target level, this parameter specifies if the object requests should be generated for that level once this level's RFP is complete. This parameter will only be applied to the RFP if it is created during the processing of this command.

*YES - Requests for the next level will be generated upon completion of the RFP into this level.

*NO - Requests for the next level will not be generated.

Assign RFP to Next Level Reqs (AREQ)

If a level exists to migrate after this target level, this parameter specifies if the generated object requests should be assigned to an RFP. This parameter will only be applied to the RFP if it is created during the processing of this command.

*YES - Requests for the next level will be assigned to a new RFP number with the same description as this RFP's number.

*NO - No, requests for the next level will not be assigned to a new RFP.

*MANUAL - Requests for the next level will be assigned to a new RFP, but the RFP will not be automatically submitted, even if the next level is set to automatically submit RFPs by default.

Place RFP in Send List (SREQ)

If distribution levels are defined for this level, this parameter specifies if the RFP should be placed in the Send List. This parameter will only be applied to the RFP if it is created during the processing of this command.

*YES - The RFP will be placed in the send list upon completion of the installation.

*NO - The RFP will not be placed in the send list.

*MANUAL - The RFP will be placed in the send list, but the RFP will not be automatically sent, even if the level is set to automatically send RFPs by default.

Lock Request (LOCK)

Specifies whether or not the Request will be placed in Locked status

*YES - The Source/Object will be locked for check-out by this request. The Source or Object may not already be locked by another request for this Request to be created.

*NO - The Request will be created in Unlocked status. Other requests for the same Source or Object may exist.

Compile Subsequence (CSQO)

Specifies the sequence for compiling (lowest first) for objects in same RFP that have the same primary sort sequence in order to handle potential dependency issues. This parameter is not relevant for *IFS Objects.

Data Origin for Physical Files or SQL Tables (DATA)

Specifies the origin of the data that should be copied into a new or modified physical file/SQL Table

*SAME - The data is mapped from the old format of the modified file to the new format of the file of the same name/target library.

*MIGRATE - The data is migrated with the file from the check-out location to the target library.

*NONE - The data is not migrated. The new file format will be empty. *NONE is required for a logical file if it is replacing a physical file.

character-value - Specify the name of the file from which to migrate the data. The data origin file must exist in the same library as the target file at the time of installation.

Data Member to Copy (DMBR)

Specifies the member(s) to copy to the new version of a physical file/SQL Table or to migrate from the prior environment.

*ALL - All existing members are included for the copy. If the target is an SQL Table, only the first member will be copied.

*FIRST - The first member in the originating file is copied. Any other members are omitted.

character-value - The name of the specific member to be copied from the originating file. Any other members are omitted.

Use MDRapid (RPGM)

Specifies if MDRapid should be used to map the data from the old version of a file to the new version.

*DFT - MDRapid will be used for modify and recompile requests if the number of records in the file is at least the number in the MDRapid template for the attribute. Otherwise not.

*YES - MDRapid will be used for the file, even if it wouldn't qualify for MDRapid processing or is for an update request.

*NO - MDRapid will not be used for the file, even if it would qualify for MDRapid processing.

Automatically Reapply Journaling (RJRN)

Specifies if the new version of a table or access path should have the journaling attributes applied to it that belonged to the file that it replaced.

*DFT - The default defined for the Application is used

*YES - If journaling was used on the prior version of the file, it will be applied to the new version.

*NO - Journaling will not be automatically reapplied. Commands run during the installation, or external processes, will determine the definition.

Automatically Reapply Constraints (RCST)

Specifies if the new version of a table should have the constraints applied to it that belonged to the table that it replaced.

*DFT - The default defined for the Application is used

*YES - If constraints were used for the prior version of the table, they will be applied to the new version.

*NO - Constraints will not be automatically reapplied. Commands run during the installation, or external processes, will determine the definition.

Automatically Reapply Triggers (RTRG)

Specifies if the new version of a table should have the system (non-SQL) triggers applied to it that belonged to the table that it replaced.

*DFT - The default defined for the Application is used

*YES - If SQL triggers were used for the prior version of the table, they will be applied to the new version. Any SQL triggers that should be re-applied should be requested for recompile and placed on same RFP as the file.

*NO - Triggers will not be automatically reapplied. Commands run during the installation, or external processes, will determine the definition.

Automatically Reapply Logical File Members (RLFM)

Specifies if the new version of a logical file should have the members added to it that belonged to the logical file that it replaced.

*DFT - The default defined for the Application is used

*YES - Any members that existed for the prior version of the logical file will be added to the new version.

*NO - Members will not be automatically reapplied. Commands run during the installation, or external processes, will determine the definition.

IFS Object is a Directory (DIR)

Specifies whether or not the Request of an object of type *IFS is a directory.

*NO - The Requested Object is not an IFS Directory

*YES - The Requested Object is an IFS Directory

Environment ID (ENV)

Specifies the MDCMS environment that should be used to place the Request. The ID correlates to the suffix of the MDCMS library name. For example, TEST correlates to library MDCMSTEST.

*DFT - The default environment will be used. This correlates to library MDCMS.

*CUR - The environment currently in the library list will be used

Vendor Reference ID (VREF)

Specifies the Vendor Generated Identifier in order for an external process to easily identify the transaction record in the MDDAREQ table. Any value up to 20 characters in length can be used.

Exception Message Returned (EMSG)

Specifies if and to what extent an exception message should be returned to the calling program. An exception message occurs when an input parameter value is invalid, causing the addition of the request to fail.

*DIAG - A diagnostic message will be placed in the calling program's message queue in the following format:

MDADDREQ Exception. Object=, Vendor Reference=, Reason=

If the Vendor Reference isn't passed to MDADDREQ, it won't be included in the diagnostic message.

*ESCAPE - The full diagnostic message as described above will be placed in the calling program's message queue and then followed by escape message CPF0001 for which the calling program can monitor.

*NONE - An exception message will not be returned to the calling program's message queue.

MDDAREQ EXAMPLE for invoking API and retrieving exception details

This example is a snippet of CL source that tries to create a new request for an SQL Table and add the request to an auto-generated RFP based on the description. The CL then monitors for an exception and retrieves the details of the exception for the diagnostic message.

DCL VAR(&KEY) TYPE(*CHAR) LEN(4)

DCL VAR(&MSG) TYPE(*CHAR) LEN(132)

MDADDREQ APPL(TEST) LVL(10) OBJT(*SQLTAB) ATTR(SQLTABIFS) +

OBJN('CUSTOMER_TABLE') SRCN('CUSTOMER_TABLE.sql') +

USER(MMORGAN) FSLB('/home/mmorgan/source') PROJ(MODERNIZE) +

ARFP(*AUTO) RFPD('modernize customer table') DATA(CUSTTAB) +

VREF(A123CX) EMSG(*ESCAPE) EMSG(*ESCAPE)

MONMSG MSGID(CPF0001) EXEC(DO)

RCVMSG MSGTYPE(*LAST) RMV(*NO) KEYVAR(&KEY)

RCVMSG MSGTYPE(*PRV) MSGKEY(&KEY) RMV(*NO) KEYVAR(&KEY) MSG(&MSG)

ENDDO