Materialize or Verify Licensed Internal Code Options (MVLICOPT)

Instruction Syntax

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. Then the materialized string for this category would be "Keyword1,Keyword2=A,Keyword3=9". A valid input string for the same 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
2 =
Verify Licensed Internal Code options
UBin(4)
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

Offset  
Dec Hex Field Name Data Type and Length
0
0
Result code
0 =
Operation successful
1 =
Error detected
UBin(4)
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

  • None

Lock Enforcement

  • None

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 220B Object Not Available
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
  • 32 Scalar Specification
    • 3203 Scalar Value Invalid
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 38 Template Specification
    • 3801 Template Value Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed
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.