Verify Licensed Internal Code Options (MVLICOPT)


Bound program access
Built-in number for MVLICOPT is 613.
MVLICOPT (
          Licensed Internal Code_options   : address
          control_options                  : address
          result_template                  : address
)

Description

The values in the supplied Licensed Internal Code options operand are verified, based on the category specified by the control options. The result of the verification is returned in the result template operand. The types of errors that verification can detect include unrecognized option keywords and other invalid tokens. A complete list of errors that can be detected is described in Table 3 (excluding result subcode zero, which means no errors were found).

The valid Licensed Internal Code options for a given category are specified with the description of that category's instruction or function, and are not further described here.

The Licensed Internal Code options operand specifies the address of an area that supplies Licensed Internal Code options to be verified. The Licensed Internal Code options length field specifies the length of the string to be verified.

The values verified from the Licensed Internal Code options operand area are presumed to use the Unicode character set. (See The Unicode Standard: Worldwide Character Encoding, Version 4.0, ISBN pending.) Options are separated by commas, and some options may accept values. During verification, the case of option keywords is ignored (though the case of option values may be significant). Multiple occurrences of the same option are allowed, but mutually exclusive option keywords aren't allowed in the same string. (1)

The special characters used in the Licensed Internal Code options operand are described in the following table:


Table 1. Licensed Internal Code options special characters

ASCII character(s)
Hex value
Use
comma (,)
002C
Separate options
single quote (')
0027
Contain text strings
equals sign (=)
003D
Assign values to options
character 9
0039
Indicates numeric option value (materialize)
character A
0041
Indicates alphabetic option value (materialize)
characters 0x
00410078
Indicates the following characters should be treated as a hexadecimal numeric value (verify, create)
backslash (\)
005C
Escape character. Indicates that the following character in a character value is not to be interpreted as a special character (verify, create). With the exception of the backslash and quote characters, special characters within a quoted string do not need to be escaped.
space
0020
Ignored between tokens (verify, create)
asterisk (*)
002A
Ignored between tokens (verify, create). A keyword preceded by an asterisk means that the option was not applied when processed because the keyword was not recognized on the system where it was last processed by the associated instruction or operation. (See Licensed Internal Code options category for additional information.)
plus sign (+)
002B
Ignored between tokens (verify, create). A keyword preceded by a plus sign means that the option was ignored when processed because there is at least one other occurrence of the same keyword in the string. When multiple occurrences exist, the last one is the one that is applied.(2)

The use of special characters is illustrated with the following example. Suppose a category consists of three Licensed Internal Code options, with keywords "Keyword1", "Keyword2", and "Keyword3". Further, suppose that "Keyword1" accepts no value, while "Keyword2" accepts a character string value, and "Keyword3" accepts a numeric value. A valid input string for this category might be "Keyword2 ='The quick brown fox' , KEYWORD1, keyword3= 0x1234".

The control options specify which category of Licensed Internal Code options is to be selected.

The format of the control options template is:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Licensed Internal Code options length
UBin(4)
4 4
Operation code
UBin(4)



2 = Verify Licensed Internal Code options



8 8
Licensed Internal Code options category
UBin(4)
12 C
Licensed Internal Code options sub-category
UBin(4)
16 10
Reserved (binary 0)
Char(48)
64 40
--- End ---

The Licensed Internal Code options length field specifies the length of the options string (in two-byte characters). The length value cannot be greater than 65,535 or a template value invalid  (hex 3801) exception is signalled.

The operation code field specifies that a verify operation is to be performed. A value of 2 indicates that the supplied options string should be verified, using the specified category and subcategory. If the value of operation code is invalid then a template value invalid  (hex 3801) exception is signalled.

The Licensed Internal Code options category field identifies the instruction or operation for which options are being verified. The valid values are shown in the table below. If the value of Licensed Internal Code options category is invalid then a template value invalid  (hex 3801) exception is signalled.

The Licensed Internal Code options subcategory field identifies the function or subset of the above-specified instruction or operation for which options are being verified. The valid values are shown in the table below. If the value of Licensed Internal Code options subcategory is invalid then a template value invalid  (hex 3801) exception is signalled.


Table 2. Licensed Internal Code options categories and sub-categories

Instruction or Operation
Category
Sub-categories
Module Creation
3
0

For the list of Licensed Internal Code options defined for category 3, see the ILE Concepts book (SC41-5606).

The format of the result template is as follows:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Result code
UBin(4)



0 = Operation successful
1 = Error detected



4 4
Result subcode
UBin(4)
8 8
Error offset
UBin(4)
12 C
Reserved (binary 0)
Char(20)
32 20
--- End ---

The result code field returns an indication of the success of the verify operation. A value of 0 indicates that the verification was successful and no errors were found. A value of 1 indicates that errors were found during the verification.

The result subcode field returns a code identifying the cause of the verify failure in the event that result code has a value of 1.

The result subcode values and their meanings are listed in the following table:


Table 3. Licensed Internal Code options result subcodes

Result subcode value Meaning
0
Verification was successful.
1
LICOPT string is ill-formed. This means that there is a syntax error in the string. It's due to an invalid character or other token occuring in the string where it doesn't belong.
2
Keyword is invalid.
3
Value has incorrect type. The value being assigned to an option has the wrong type.
4
Value is out of range. The value being assigned to an option is not in the valid range of values allowed for the option.
5
Keyword is the opposite of a prior keyword. This happens when two mutually exclusive Licensed Internal Code keywords are specified in the same string, which is invalid. Mutually exclusive keywords specify opposite options. An example of a pair of mutually exclusive keywords is BindStatic and NoBindStatic.
6 String keyword is not assigned an allowable value. A Licensed Internal Code keyword that takes a string value has been assigned a value that is not permitted for that keyword.

The error offset field returns the offset, in two-byte characters, to the point where the first error was detected in the options string. Error offset is set to 0 if result code indicates that verification was successful.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

32 Scalar Specification

2E Resource Control Limit

38 Template Specification

44 Protection Violation

Footnotes:

(1) Mutually exclusive keywords specify opposite options. An example of a pair of mutually exclusive keywords is BindStatic and NoBindStatic.

(2) This is true in general, but there are exceptions. Some keywords can be specified multiple times in order to provide multiple pieces of information. For these, none of the keywords will be preceded by a plus sign, since they will all have been applied.