Declare Processing Options (DCLPRCOPT)
Where allowed to run:
|
Parameters Examples Error messages |
The Declare Processing Options (DCLPRCOPT) command lets you define compiler processing options. These options can control the behavior of the compiler or modify the attributes of the program or module object generated by the CL compiler.
You can use the DCLPRCOPT command to set compiler parameters in your CL source program instead of specifying the same parameters on the CL command used to invoke the CL compiler (CRTCLPGM, CRTCLMOD or CRTBNDCL).
- These parameters on DCLPRCOPT do not have default values. If no value is specified, the CL compiler uses the value specified or defaulted on the CL command used to invoke the CL compiler.
- Setting a parameter value on DCLPRCOPT will override any value specified or defaulted for the corresponding parameter on the CRTCLPGM, CRTCLMOD, or CRTBNDCL command.
- If a compiler listing is generated, the first page will show the compiler parameters passed in from the CL command used to invoke the CL compiler. Any of these parameters overridden by a DCLPRCOPT command will affect the generated CL program or CL module, and will be reflected on the first page of the compiler listing also.
- Some parameters and parameter values only apply to the original program model (OPM) CL compiler or the integrated language environment (ILE) CL compiler. For example, the ACTGRP parameter is only applicable to the ILE CL compiler invoked by the CRTBNDCL command. Parameters or values specified on DCLPRCOPT which are not applicable to the CL compiler invoked to compile the CL source program are ignored.
Restrictions:
- This command is valid only within a CL program or ILE CL procedure. All declare commands (DCL, COPYRIGHT, DCLF, and DCLPRCOPT) must follow the PGM (Program) command and must precede all other commands in the program. The four types of declare commands can be intermixed in any order.
- Only one DCLPRCOPT command is allowed by the CL compiler; if multiple DCLPRCOPT commands are specified in the CL source program, message CPD0323 is sent and the compile fails.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| SUBRSTACK | Subroutine stack depth | 20-9999, 99 | Optional, Positional 1 |
| LOG | Log commands | *JOB, *YES, *NO | Optional |
| ALWRTVSRC | Allow RTVCLSRC | *YES, *NO | Optional |
| TEXT | Text 'description' | Character value, *SRCMBRTXT, *BLANK | Optional |
| USRPRF | User profile | *USER, *OWNER | Optional |
| AUT | Authority | Name, *LIBCRTAUT, *CHANGE, *ALL, *USE, *EXCLUDE | Optional |
| DBGENCKEY | Debug encryption key | Character value, *NONE | Optional |
| STGMDL | Storage model | *SNGLVL, *TERASPACE | Optional |
| DFTACTGRP | Default activation group | *YES, *NO | Optional |
| ACTGRP | Activation group | Name, *STGMDL, *NEW, *CALLER | Optional |
| BNDSRVPGM | Bind service program | Single values: *NONE Other values (up to 300 repetitions): Element list |
Optional |
| Element 1: Service program | Qualified object name | ||
| Qualifier 1: Service program | Generic name, name, *ALL | ||
| Qualifier 2: Library | Name, *LIBL | ||
| Element 2: Activation | *IMMED, *DEFER | ||
| BNDDIR | Binding directory | Single values: *NONE Other values (up to 300 repetitions): Qualified object name |
Optional |
| Qualifier 1: Binding directory | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB, *USRLIBL |
| Top |
Subroutine stack depth (SUBRSTACK)
Specifies how many entries you want to allow on the subroutine stack. Each time a CALLSUBR (Call Subroutine) command is run, an entry is added on the subroutine stack. The entry is removed when a RTNSUBR (Return from Subroutine) or ENDSUBR (End Subroutine) command is run. The subroutine stack can have multiple entries when CALLSUBR commands are run from within a subroutine; a subroutine can invoke another subroutine or recursively invoke itself.
- 99
- The maximum number of subroutine stack entries allowed when this CL program is run is 99.
- 20-9999
- Specify the maximum number of subroutine stack entries allowed when this CL program is run.
| Top |
Log commands (LOG)
Specifies the logging options for a created CL program or module.
- *JOB
- Logging of commands in a running CL program depends on the status of the job's logging flag (see the LOGCLPGM parameter of the Change Job (CHGJOB) command). To list the logged commands, the logging level of the jobs must be 3 or 4.
A *YES or *NO value takes precedence over any value specified in the CHGJOB command.
- *YES
- The commands are logged in all cases.
- *NO
- The commands are not logged.
| Top |
Allow RTVCLSRC (ALWRTVSRC)
Specifies whether the CL source is saved with the module or program object. Source that is saved can be retrieved later by using the Retrieve CL Source (RTVCLSRC) command.
- *YES
- Source for the CL program is saved with the program.
- *NO
- Source for the CL program is not saved with the program.
| Top |
Text 'description' (TEXT)
Specifies text that briefly describes the compiled CL program or module object.
- *SRCMBRTXT
- The text is taken from the source file member used to create the CL program or module. If the source file is an inline data file or a device file, the text is blank.
- *BLANK
- Text is not specified.
- character-value
- Specify no more than 50 characters of text, enclosed in apostrophes.
| Top |
User profile (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.
Note: This parameter is ignored if REPLACE(*YES) is specified and a program already exists with the name specified by the PGM parameter on the CRTCLPGM or CRTBNDCL command.
Note: This parameter is only applicable if the CL source is compiled using the CRTCLPGM or CRTBNDCL command. For CRTCLMOD, any value specified for this parameter is ignored.
- *USER
- The program runs under the user profile of the program's user.
- *OWNER
- The user profiles of both the program's owner and the program's user are used when the program is processed. The collective sets of object authority in both user profiles are used to find and access objects during program processing. Authority from the owning user profile's group profile is not included in the authority for the running program.
| Top |
Authority (AUT)
Specifies the authority you are granting to the users who do not have specific authority for the object, who are not on the authorization list, and whose user group has no specific authority for the object.
Note: This parameter is ignored when REPLACE(*YES) is specified and an object by the specified name already exists in the specified library.
- *LIBCRTAUT
- The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library (CRTLIB) command for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will 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 (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.
- *ALL
- The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) 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 object.
- *USE
- The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.
- *EXCLUDE
- The user cannot access the object.
- name
- Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.
| Top |
Debug encryption key (DBGENCKEY)
Specifies the encryption key to be used to encrypt program source that is embedded in debug views.
Note: This parameter is only applicable if the CL source is compiled using the CRTBNDCL or CRTCLMOD commands. For CRTCLPGM, any value specified for this parameter is ignored.
- *NONE
- No encryption key is specified.
- character-value
- Specify the key to be used to encrypt program source that is embedded in debug views stored in the module object. The length of the key can be between 1 and 16 bytes. A key of length 1 to 15 bytes will be padded to 16 bytes with blanks for the encryption. Specifying a key of length zero is the same as specifying *NONE.
If the key contains any characters which are not invariant over all code pages, it will be up to the user to ensure that the target system uses the same code page as the source system, otherwise the key may not match and the decryption may fail. If the encryption key must be entered on systems with differing code pages, it is recommended that the key be made of characters which are invariant for all EBCDIC code pages.
| Top |
Storage model (STGMDL)
Specifies the storage model attribute of the ILE CL program.
Note: This parameter is only applicable if the CL source is compiled using the CRTBNDCL command. For CRTCLPGM and CRTCLMOD, any value specified for this parameter is ignored.
- *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. STGMDL(*TERASPACE) cannot be specified if DFTACTGRP(*YES) is specified.
| Top |
Default activation group (DFTACTGRP)
Specifies whether the ILE CL program is associated with the default activation group.
Note: This parameter is only applicable if the CL source is compiled using the CRTBNDCL command. For CRTCLPGM and CRTCLMOD, any value specified for this parameter is ignored.
- *YES
- The program is associated with the default activation group.
Note: If this value is specified, the ACTGRP parameter cannot be specified.
- *NO
- The program is not associated with the default activation group.
| Top |
Activation group (ACTGRP)
Specifies the activation group that the ILE CL program is associated with when it is called. The 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
Note: This parameter is only applicable if the CL source is compiled using the CRTBNDCL command. For CRTCLPGM and CRTCLMOD, any value specified for this parameter is ignored.
- *STGMDL
- IF STGMDL(*SNGLVL) is specified, this program will be activated into the QILE activation group when it is called. If STGMDL(*TERASPACE) is specified, the program will be activated into the QILETS activation group when it is called.
- *CALLER
- When this program gets called, the program is activated into the caller's activation group.
- *NEW
- When this program gets called, the system creates a new activation group.
- name
- Specify the name of the activation group to be used when this program is called.
| Top |
Bind service program (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. Up to 300 names can be specified.
You can control the activation of each service program. You can specify whether the referenced service program is activated at the same time as the program is being created, or is deferred until a procedure exported from the referenced service program is called. Deferring activation may improve your application's performance.
Note: This parameter is only applicable if the CL source is compiled using the CRTBNDCL command. For CRTCLPGM and CRTCLMOD, any value specified for this parameter is ignored.
Single values
- *NONE
- No service program is specified.
Element 1: Service program
Qualifier 1: Service program
- *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.
- generic-name
- Specify all service program objects starting with the characters preceding the * in the specified library or libraries.
- name
- Specify the name of the service program to be examined during symbol resolution.
Qualifier 2: Library
- *LIBL
- All libraries in the library list for the current thread are searched until the first match is found.
- name
- Specify the name of the library to be searched.
Note: QTEMP is not a valid library name for this parameter.
Element 2: Activation
- *IMMED
- The referenced service program is activated when the program being created is activated.
- *DEFER
- The referenced service program is activated when a procedure it exports is called.
| Top |
Binding directory (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. Up to 300 names can be specified.
Note: If any modules in a specified binding directory export a procedure that is referenced by a CALLPRC command in the CL source being compiled, DFTACTGRP(*NO) must be specified along with a value for the ACTGRP parameter. If DFTACTGRP(*YES) is specified (or defaulted) on the CRTBNDCL command, the resulting program can only contain a single *MODULE object.
Note: This parameter is only applicable if the CL source is compiled using the CRTBNDCL command. For CRTCLPGM and CRTCLMOD, any value specified for this parameter is ignored.
Single values
- *NONE
- No binding directory is specified.
Qualifier 1: Binding directory
- name
- Specify the name of the binding directory used in symbol resolution.
Qualifier 2: Library
- *LIBL
- All libraries in the library list for the current thread are searched until the first match is found.
- *CURLIB
- The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
- *USRLIBL
- Only the libraries in the user portion of the thread's library list are searched.
- name
- Specify the name of the library to be searched.
| Top |
Examples
Example 1: Declaring the Subroutine Stack Depth
DCLPRCOPT SUBRSTACK(50)
This command sets the maximum number of subroutine stack entries to 50. When the CL program is run, if the subroutine stack depth exceeds 50, escape message CPF0822 will be sent.
Example 2: Declaring Compiler Options to Override CRTCLPGM
DCLPRCOPT ALWRTVSRC(*NO) USRPRF(*OWNER)
This command will override the Allow RTVCLSRC (ALWRTVSRC) and User profile (USRPRF) values specified on the Create CL Program (CRTCLPGM) command. The resulting CL program will not allow the CL source code to be retrieved from the *PGM object and when the program object is called it will adopt the authorities of the user profile that owns the *PGM object.
Example 3: Declaring Compiler Options to Override CRTCLMOD
DCLPRCOPT LOG(*NO) AUT(*USE)
This command will override the Log commands (LOG) and Authority (AUT) values specified on the CRTCLMOD command. Once the resulting ILE CL module is bound into an ILE program or service program and the ILE CL procedure is called, CL commands run from this procedure will not be logged in the job log. The public authority for the *MODULE object created by the Create CL Module (CRTCLMOD) command will be *USE.
Example 4: Declaring Compiler Options to Override CRTBNDCL
DCLPRCOPT DFTACTGRP(*NO) ACTGRP(MYAPP) +
BNDDIR(MYAPPLIB/MYBNDDIR)
This command will override the Default activation group (DFTACTGRP) and Activation group (ACTGRP) values specified on the Create Bound CL Program (CRTBNDCL) command. The resulting ILE CL program will run in the MYAPP named activation group. When CRTBNDCL runs the Create Program (CRTPGM) command, it will add binding directory MYBNDDIR in library MYAPPLIB on the Binding directory (BINDIR) parameter. This will make the service programs and ILE modules referenced by that binding directory available to resolve ILE procedures used in the ILE CL program.
| Top |
Error messages
None
| Top |