CRTPGM (Create Program)

CRTPGM Command syntax diagram

 

Purpose

The Create Program (CRTPGM) command creates a bound program from a set of modules and binding directories.

 

Restrictions

1. You must have *READ and *ADD authority for the library where the program is being created.
   
2. You must have *USE authority to the specified modules, service programs, and binding directories.

 

Required Parameters

PGM

Specifies the qualified name of the program object created.

The name of the program object can be qualified by one of the following library values:

*CURLIB: The program object is created in the current library for the job. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the program object is created.

program-name: Specify the name of the created program.

 

Optional Parameters

MODULE

Specifies the list of modules that are copied and bound together to create the program object. If duplicate module and library specifications are found, only the first instance of the duplicate module and library is used. Modules in this list are copied into the final program object.

*PGM: The name specified on the PGM parameter is used as the module object name. The library specified on the PGM parameter is also used.

The name of the module list can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

library-name: Specify the name of the library to be searched.

*ALL: Find all module objects in the specified library or libraries.

generic*-module-name: Specify all module objects starting with the characters preceding the * in the specified library or libraries.

module-name: Specify the name of the module that is copied to create the program object.

ENTMOD

Specifies the module name that contains the program entry procedure specification to be used for this program.

*FIRST: The first module found, from the list of modules, that has a program entry procedure specification is selected as the program entry procedure.

*ONLY: Only one module, from the list of modules, can have a specification as the program entry procedure. An error is issued if more than one module is found to have a program entry procedure specification.

*PGM: The name and library specified on the PROGRAM parameter will be the name and library of the module which has the program entry procedure specification.

The name of the specified module can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

library-name: Specify the name of the library to be searched.

module-name: Specify the module containing the program entry procedure specification. If this module is not in the list of modules to be included in this program, it is added to the list of modules. If this module does not have a program entry procedure specification, the program is not created.

BNDSRVPGM

Specifies the list of service program exports to examine at bind time to ensure they satisfy any module import requests. The service program exports are checked only if there are unresolved module import requests not satisfied by the set of module exports. Any service program specified on the BNDSRVPGM parameter that satisfies a module import request will be bound to the program being created. The service program name and the library specified on the BNDSRVPGM parameter are saved to be used at run time.

*NONE: No service program is specified.

The name of the service program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

library-name: Specify the name of the library to be searched.

Note:

QTEMP is not a valid library name for this parameter.

*ALL: Find all service program objects in the specified library or libraries.

Note:

This value should only be specified in a user-controlled environment when you know exactly what is getting bound to your program. Specifying *LIBL with *ALL may give you unpredictable results at program run time. Specify the generic service program name or specific libraries to better control what gets bound to your program.

service-program-name: Specify the name of the service program to be examined during symbol resolution.

generic*-program-name: Specify all service program objects starting with the characters preceding the * in the specified library or libraries.

BNDDIR

Specifies the list of binding directories that are used in symbol resolution. The exports of the modules and service programs in the binding directory are only checked if there are unresolved module import requests that the exports from the modules and service programs (specified in the MODULE or BNDSRVPGM parameters) could not satisfy.

*NONE: No binding directory is specified.

The name of the binding directory can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

library-name: Specify the name of the library to be searched.

binding-directory-name: Specify the name of the binding directory used in symbol resolution.

ACTGRP

Specifies the activation group this program is associated with when it is called. An activation group provides:

• Run-time data structures to support the running of programs
  
• Addressing protection
  
• A logical boundary for message creation
  
• A logical boundary for application cleanup processing

*NEW: When this program gets called, a new activation group is created. This called program is then associated with the newly created activation group.

*CALLER: When this program gets called, the program is activated into the caller's activation group.

activation-group-name: Specify the name of the activation group to be used when this program is called.

OPTION

Specifies options to be used when the program object is created.

Program Creation Options

*GEN: A program object is generated.

*NOGEN: A program object is not generated.

Duplicate Procedure Name Options

*NODUPPROC: During the symbol resolution phase of the binding process, each procedure name that is exported from the modules and service programs must be unique.

*DUPPROC: During the symbol resolution phase of the binding process, the procedure names that are exported from the modules and service programs do not have to be unique. When multiple duplicate procedures are allowed, the first exported procedure in the list of specified modules and service programs that matches the import request is the procedure that is selected.

Duplicate Variable Name Options

*NODUPVAR: During the symbol resolution phase of the binding process, each variable name that is exported from the modules and service programs must be unique.

*DUPVAR: During the symbol resolution phase of the binding process, the variable names that are exported from the modules and service programs do not have to be unique. When multiple duplicate variables are allowed, the first exported variable in the list of specified modules and service programs that matches the import request is the variable that is selected.

Diagnostic Message Options

*WARN: If duplicate variables or procedures are found, a diagnostic message is issued indicating what duplicates were found.

*NOWARN: If duplicate variables and procedures are found, diagnostic messages are not issued.

Resolving References Options

*RSLVREF: All imports must be resolved to exports for the program to be created.

*UNRSLVREF: All imports do not need to resolve to exports for the program to be created. If the program tries to use one of these unresolved imports at run time, an MCH3203 exception message is issued. If creating a program for a V3R1 or later release and the program uses one of the unresolved references, a MCH4439 run time exception is issued.

DETAIL

Specifies the level of detail to be printed.

*NONE: A listing is not generated.

*BASIC: Contains a listing of the options passed to CRTPGM, and processing statistics. This listing also contains the Brief Summary Table.

*EXTENDED: In addition to the information provided in the *BASIC listing, this listing contains the Extended Summary Table and the Binding Information Listing.

*FULL: This listing contains the *EXTENDED listing and the Cross-Reference Listing.

Note:

If a printed listing is requested, the printer file *LIBL/QSYSPRT is used to generate the listing.

ALWUPD

Specifies whether to allow an update of the program being created using the Update Program (UPDPGM) command.

*YES: This program can be updated in the future using the UPDPGM command.

*NO: The UPDPGM command does not update the program being created.

ALWLIBUPD

Specify whether to allow the bound service program library name to be changed on update, using the UPDPGM command, of the program being created.

*NO: The UPDPGM command will never be allowed to update the bound service program library names of the program being created, even if ALWUPD is *YES.

*YES: This program may have the bound service program library names updated at any future time using the UPDPGM command, as long as the ALWUPD is also *YES.

USRPRF

Specifies whether the authority checking done while this program is running includes only the user who is running the program (*USER) or both the user running the program and the program owner (*OWNER). The profiles of the program user or both the program user and the program owner are used to control which objects can be used by the program, including the authority the program has for each object. Only the program owner or a user with QSECOFR authority can change the user profile attribute.

*USER: The program runs under the user profile of the program's user.

*OWNER: The user profiles of both the program owner and the program user are used when the program is run.

REPLACE

Specifies whether the existing program is replaced if a program by the same name already exists in the specified library.

*YES: Replace the existing program by moving it to the QRPLOBJ library.

Note:

Both programs must be owned by the same user for the replace to work.

*NO: No replacement occurs.

AUT

Specifies the authority given to users who do not have specific authority to the program, who are not on an authorization list, and whose user group has no specific authority to the program.

*LIBCRTAUT: The public authority for the program is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the program). The public authority is determined when the program is created. If the CRTAUT value for the library changes after the program is created, the new value does not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the program.

*USE: The user can perform basic operations on the program, such as running a program or reading a file. The user cannot change the program. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the program.

authorization-list: The authorization list must exist when the object is created. Users are granted authority to the object as specified by the list.

TEXT

Specifies the text that briefly describes the program object. More information on this parameter is in Commonly used parameters.

*ENTMODTXT: The text description of the module specified on the ENTMOD parameter is used.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

TGTRLS

Specifies the release level of the operating system on which you intend to use the object being created.

When specifying the target-release value, the format VxRxMx is used to specify the release, where Vx is the version, Rx is the release, and Mx is the modification level. For example, V3R6M0 is version 3, release 6, modification level 0.

Valid values depend on the current version, release, and modification level, and they change with each new release. See the Valid Values for TGTRLS Parameter table in the Backup and Recovery book for a complete list of valid values.

*CURRENT: The object is to be used on the release of the operating system currently running on your system. The object can also be used on a system with any subsequent release of the operating system installed.

*PRV: The object is to be used on the previous release with modification level 0 of the operating system. The object can also be used on a system with any subsequent release of the operating system installed.

target-release: Specify the release in the format VxRxMx. The object can be used on a system with the specified release or with any subsequent release of the operating system installed.

ALWRINZ

Specifies if the static storage of the program is allowed to be reinitialized while it is still active.

*NO: The static storage of the program can not be reinitialized while it is still active.

*YES: The static storage of the program is allowed to be reinitialized while the program is still active.

STGMDL

Specifies the storage model attribute of the program.

*SNGLVL: The program is created with single-level storage model. When a single-level storage model program is activated and run, it is supplied single-level storage for automatic and static storage. A single-level storage program runs only in a single-level storage activation group.

*TERASPACE: The program is created with teraspace storage model. When a teraspace storage model program is activated and run, it is supplied teraspace storage for automatic and static storage. A teraspace storage program runs only in a teraspace storage activation group.

IPA

Specifies whether interprocedural analysis (IPA) is to be used during the program creation. For more information on IPA, refer to the ILE Concepts book.

*NO: Interprocedural analysis will not be performed.

*YES: Interprocedural analysis will be performed. Note that the resulting program will not be allowed to be updated with the Update Program (UPDPGM) command.

IPACTLFILE

Gives the path name of a file which contains interprocedural analysis (IPA) suboption information. This parameter is allowed only when IPA(*YES) is specified.

*NONE: No IPA control file information is to be used when IPA(*YES) is specified.

'IPA-control-file': Specifies the path name of the IPA control file to use when IPA(*YES) is specified. If the name is qualified it must be enclosed in apostrophes. An example of a qualified IPA control file name is '/directory1/directory2/myipactlfname'

Example for CRTPGM

CRTPGM   PGM(STAR)

This command creates a program object named STAR in the current library or QGPL.

Error messages for CRTPGM

*ESCAPE Messages

CPF223E

Authority check for use adopted authority attribute failed.

CPF3C50

Program &1 not created.

CPF5D12

Error encountered during program or service program preparation.