HP 3000 Manuals HP 3000 Manuals
Operation Definitions (Cont) LOCK, UNLCK These file operations let you conditionally or unconditionally lock and unlock TurboIMAGE, KSAM, and MPE files. You can lock TurboIMAGE files at the database, data set, or record level. You can lock KSAM and MPE files at the file level. (For all of these file types, MPE/iX performs page level locking automatically.) Unconditionally locking a file means that the process is suspended, if necessary, until the database, data set, record, or file is unlocked by another process[REV BEG] which has it locked.[REV END] The interval during which the process is suspended can seriously degrade performance in an interactive processing environment. To avoid this, use conditional locking. Conditionally locking a database, data set, record, or file means that if the entity is already locked by another process, the lock fails and a resulting indicator is turned ON. The process that performed the lock continues with the next operation. For the LOCK and UNLCK operations to be allowed for shared files, the appropriate locking facility must be enabled. For TurboIMAGE files, enter a B, S, 1, 9, or L (L is recommended) in the Open Mode Field (column 66) in the Database Name (IMAGE) line of the File Description Continuation line. For KSAM and MPE files, you enable locking by specifying either LOCK or NOLOCK in the Option Type Field (column 54-59) of a File Description Continuation line for the file.
NOTE You can use LOCK and UNLCK even though you use a locking mode that causes RPG to automatically lock and unlock the file for you. However, you should exercise extreme caution when doing this. You must ensure that your manual locking does not interfere with RPG automatic locking.
Table 8-12 summarizes the type of locks that you can perform and the fields that you must enter in the Calculation Specification to accomplish them. Table 8-12. Calculation Specification Fields Used with LOCK and UNLCK ------------------------------------------------------------------------------------------------------- | | | | | | | | File and | Factor 1 | Operation | Factor 2 | Result | Field | | Level of Lock | | | | Field | Length | | | | | | | | ------------------------------------------------------------------------------------------------------- | | | | | | | | TurboIMAGE | blank | LOCK/UNLCK | filename | database | 1-256 | | Database | | | | | | | | | | | | | | TurboIMAGE | blank | LOCK/UNLCK | filename | blank | blank | | Data set | | | | | | | | | | | | | | TurboIMAGE | key value | LOCK/UNLCK | filename | blank | blank | | Record | | | | | | | | | | | | | | KSAM file | blank | LOCK/UNLCK | filename | blank | blank | | | | | | | | | MPE file | blank | LOCK/UNLCK | filename | blank | blank | | | | | | | | ------------------------------------------------------------------------------------------------------- TurboIMAGE Files The following items discuss how to lock TurboIMAGE files at the database, data set, and data set record level. * Locking and Unlocking a TurboIMAGE database. Use LOCK to lock the database and UNLCK to unlock it. Leave the Factor 1 Field blank. Enter the database file name in the Factor 2 Field. This is the name defined in File Name Field (columns 7-13) of the File Description Specification. Enter the actual database name (not enclosed in quotes) in the Result Field. This is the name entered in columns 60-65 of the Database Name (IMAGE) line of the File Description Specification Continuation line. Enter a number from 1 to 256 in the Field Length Field (columns 49-51). This number is required for compatibility with other RPG implementations but is not used. Enter an indicator in the High Resulting Indicators Field (columns 54-55) to perform conditional locking. Leave this field blank to specify unconditional locking. Enter either or both a Low Resulting indicator and an Equal Resulting indicator. When LOCK is executed,[REV BEG] the Equal Resulting indicator is turned ON if the operation is successful.[REV END] Table 8-13 lists the resulting indicators and the conditions that cause them to be turned ON. Since the TurboIMAGE subsystem actually performs the locks, the TurboIMAGE status code is shown also. (For further information about the TurboIMAGE status codes, see the TurboIMAGE/iX Database Management System manual.) * Locking and Unlocking a TurboIMAGE data set. Use LOCK to lock the data set and UNLCK to unlock it. (UNLCK actually unlocks the entire database, releasing all previous locks for it.) Leave the Factor 1 Field blank. Enter the database file name in the Factor 2 Field. This is the name defined in File Name Field (columns 7-13) of the File Description Specification. Leave the Result Field blank. Enter an indicator in the High Resulting Indicators Field (columns 54-55) to perform conditional locking. Leave this field blank to specify unconditional locking. Enter either or both a Low Resulting indicator and an Equal Resulting indicator. When LOCK and UNLCK are[REV BEG] executed, the Equal Resulting indicator is turned ON if the operation was successful.[REV END] Table 8-13 lists the resulting indicators and the conditions that cause them to be turned ON. Since the TurboIMAGE subsystem actually performs the locks, the TurboIMAGE status code is shown also. (For further information about the TurboIMAGE status codes, see the TurboIMAGE/iX Database Management System manual.) * Locking and Unlocking a TurboIMAGE data set record. Use LOCK to lock the data set record and UNLCK to unlock it. (If all previous locks for the database are released, UNLCK unlocks the entire database.) Enter the key for the record you want to lock in the Factor 1 Field. This is the field defined as the key in the Item Name (ITEM) line (columns 60-74) of the File Description Specification Continuation line. Enter the database file name in the Factor 2 Field. This is the name defined in File Name Field (columns 7-13) of the File Description Specification. Leave the Result Field blank. Enter an indicator in the High Resulting Indicators Field (columns 54-55) to perform conditional locking. Leave this field blank to specify unconditional locking. Enter either or both a Low Resulting indicator and an Equal Resulting indicator. When LOCK and UNLCK are[REV BEG] executed, the Equal Resulting indicator is turned ON if the operation was successful.[REV END] Table 8-13 lists the resulting indicators and the conditions that cause them to be turned ON. Since the TurboIMAGE subsystem actually performs the locks, the TurboIMAGE status code is shown also. (For further information about the TurboIMAGE status codes, see the TurboIMAGE/iX Database Management System manual.) Table 8-13. How Resulting Indicators Are Set For LOCK/UNLCK (TurboIMAGE Files) ---------------------------------------------------------------------------------------------------- | | | | | | | Resulting | LOCK | LOCK | LOCK | UNLCK | | Indicator | Database | Data Set | Record | | | Turned ON | | | | | | | | | | | ---------------------------------------------------------------------------------------------------- | | | | | | | High | Database | Database locked or | Database locked or | Exceptional error | | (conditional | locked or | contains locks | contains locks | (TurboIMAGE | | locking only). | contains locks | (TurboIMAGE status | (TurboIMAGE status | status > 0). | | | (TurboIMAGE | 20). | 20). | [REV BEG] | | | status 20). | | | | | | | Data set locked by | Data set locked by | | | | | another process | another process | | | | | (TurboIMAGE status | (TurboIMAGE status | | | | | 22). | 22). | | | | | | | | | | | Entries locked | Entries locked | | | | | within data set | within data set | | | | | (TurboIMAGE status | (TurboIMAGE status | | | | | 23). | 23). | | | | | | | | | | | | Item conflicts | | | | | | with current locks | | | | | | (TurboIMAGE status | | | | | | 24). | | | | | | | | | | | | Entries already | | | | | | locked (TurboIMAGE | | | | | | status 25). | | | | | | | | | Low | File system or | See error messages | See error messages | File system or | | | memory manager | in the TurboIMAGE | in the TurboIMAGE | memory manager | | | failure | Reference Manual. | Reference Manual. | failure | | | (TurboIMAGE | | | (TurboIMAGE | | | status < 0). | | | status - < | | | | | | 0).[REV END] | | | | | | | | Equal | Request | Request granted | Request granted | Request granted | | | granted | (TurboIMAGE status | (TurboIMAGE status | (TurboIMAGE | | | (TurboIMAGE | 0). | 0). | status 0). | | | status 0). | | | | | | | | | | | None of the | A condition | A condition not | A condition not | Does not apply; | | above indicators | not listed | listed above was | listed above was | at least one | | are turned ON. | above was | encountered | encountered | resulting | | | encountered | (TurboIMAGE status | (TurboIMAGE status | indicator is ON. | | | (TurboIMAGE | not listed above). | not listed above). | | | | status not | | | | | | listed above). | | | | | | | | | | ---------------------------------------------------------------------------------------------------- KSAM Files You can lock KSAM files at the file level. To monitor the locking and unlocking of KSAM files from a terminal, use the KSAM utility, KSAMUTIL. For complete information about KSAMUTIL, see the KSAM/3000 Reference Manual. You can lock a KSAM file at the file level only if you have specified LOCK or NOLOCK in the Option Type Field (columns 54-59) of a File Description Specification Continuation line for the file. Use LOCK to lock the file and UNLCK to unlock it. Leave the Factor 1 Field blank. Enter the file name for the KSAM file in the Factor 2 Field. This is the name defined in File Name Field (columns 7-13) of the File Description Specification. Leave the Result Field blank. Enter an indicator in the High Resulting Indicators Field (columns 54-55) to perform conditional locking. Leave this field blank to specify unconditional locking. Enter either or both a Low Resulting indicator and an Equal Resulting indicator. When LOCK is executed, the indicators that you enter are turned ON to indicate if the operation was successful. Table 8-14 lists the resulting indicators and the conditions that cause them to be turned ON. Since the KSAM subsystem actually performs the locks, the KSAM condition code is shown also. (For further information about the KSAM condition codes, see the KSAM/3000 Reference Manual.) MPE Files Use LOCK to lock an MPE file and UNLCK to unlock it. Leave the Factor 1 Field blank. Enter the file name for the MPE file in the Factor 2 Field. This is the name defined in File Name Field (columns 7-13) of the File Description Specification. Leave the Result Field blank. Enter an indicator in the High Resulting Indicators Field (columns 54-55) to perform conditional locking. Leave this field blank to specify unconditional locking. Enter either or both a Low Resulting indicator and an Equal Resulting indicator. When LOCK is executed, the indicators that you enter are turned ON to indicate if the operation was successful. Table 8-14 lists the resulting indicators and the conditions that cause them to be turned ON. Table 8-14. How Resulting Indicators Are Set For LOCK/UNLCK (KSAM and MPE Files) --------------------------------------------------------------------------------------- | | | | | Resulting | LOCK | UNLCK | | Indicator | | | | Turned ON | | | | | | | --------------------------------------------------------------------------------------- | | | | | High | Locked by another process | Not already locked | | (conditional | (KSAM condition code >). | (KSAM condition code >). | | locking only) | | | | | | | | Low | Not opened with dynamic | Not opened with dynamic | | | locking facility enabled or | locking facility enabled or | | | need MR capability | need MR capability | | | (KSAM condition code <). | (KSAM condition code <). | | | | | | Equal | Request granted | Request granted | | | (KSAM condition code =). | (KSAM condition code =). | | | | | --------------------------------------------------------------------------------------- LOKUP This table and array operation retrieves an element from a table or array and makes it available for use in subsequent operations. The element is retrieved when it satisfies the search criteria that you enter. Enter the search argument (the element you're looking for) in the Factor 1 Field. It can be an alphanumeric or numeric constant, a field name, an array element, or a table name. Enter the table or array to search in the Factor 2 Field. Be sure that Factor 1 and Factor 2 have the same length. They do not have to contain the same number of decimal places. Enter at least one but not more than two indicators in the Resulting Indicators Field (columns 54-59). The indicators define the search criteria and reveal the results of the search. Enter an indicator in the Equal Subfield (columns 58-59) to search for an element in the table or array that is equal to Factor 1 (if there is more than one equal element, the first one is chosen). Enter an indicator in the Low Subfield (columns 56-57) to search for the element that is nearest to, but less than Factor 1. Enter an indicator in the High Subfield (columns 54-55) to search for the element that is nearest to, but higher than Factor 1.[REV BEG] You cannot specify both the High and the Low Subfield in the same LOKUP operation.[REV END] When the search is successful, the indicator that you enter is turned ON. For example, if the indicator 05 is entered in the High Subfield, a search for the nearest element that is higher than Factor 1 takes place and if an element is found, indicator 5 is turned ON. You can search for a table or array element that is greater than or equal to Factor 1, or less than or equal to Factor 1. Enter indicators in both the Equal and Low Subfields or the Equal and High Subfields. Either condition satisfies the search (equal has precedence) and the indicator associated with that condition is turned ON. When you enter an indicator in the Low Subfield, High Subfield, the Equal and Low Subfields, or the Equal and High Subfields, make sure the table or array is in ascending or descending sequence,[REV BEG] or you may not retrieve the element you expect.[REV END] (You can use the SORTA operation to sequence arrays.) Searching A Table To search a table that has no alternating table, use the Factor 1, Factor 2, and Resulting Indicator Fields. To condition the LOKUP operation, enter indicators in the Control Level (columns 7-8) or Indicators Fields (columns 9-17), or both. When an element is found, use the table name in subsequent operations to reference it. The table name references the element that was found until another LOKUP operation is performed or until you use the table name in the Result Field of another operation. If an element is not found, the table name references the element found by the previous LOKUP operation. Example Figure 8-29 shows how to search a table. Suppose that the field ENTRY1 (line 1) contains the value 300. The LOKUP operation searches the table TABLEA for 300. If it is found, indicator 10 is turned ON. The ADD operation in line 2 is executed (since indicator 10 is turned ON). It adds 300 (the element found by the LOKUP in line 1) to 100, and replaces the element containing 300 in TABLEA with the result (400). ___________________________________________________________________________________ | | | 1 2 3 4 5 6 7 | | 678901234567890123456789012345678901234567890123456789012345678901234| | _______________________________________________________ | | | | 1 C ENTRY1 LOKUPTABLEA 10 | | 2 C 10 TABLEA ADD 100 TABLEA | | | | | | | ___________________________________________________________________________________ Figure 8-29. Searching a Table Searching Alternating Tables This section explains how to search a table along with its alternating table. The alternating table is not actually searched, although you name it in the LOKUP operation. However, when an element is found in a table, its corresponding alternating table values become available. To search a table and its alternating table, enter the table in the Factor 2 Field and the alternating table in the Result Field. Use the Factor 1 and Resulting Indicator Fields as you normally do, but do not enter an array element in the Factor 1 Field. The table and its alternating table should be the same length. If not, the search stops at the end of the shorter table. Once an element is found in the table, use the table name to reference it or use the alternating table name to reference elements in the alternating table. Example Figure 8-30 shows how to search the table TABLEB and its alternating table TABLEC. The LOKUP operation in line 1 searches TABLEB for the element that matches the field ENTRY2. If an element is found, indicator 20 is turned ON. The MULT operation in line 2 is executed when indicator 20 is turned ON. The element in TABLEC (found by the LOKUP operation) is multiplied by 20 and the result is placed in the field STORA. ___________________________________________________________________________________ | | | 1 2 3 4 5 6 7 | | 678901234567890123456789012345678901234567890123456789012345678901234| | _______________________________________________________ | | | | 1 C ENTRY2 LOKUPTABLEB TABLEC 20 | | 2 C 20 TABLEC MULT 20 STORA | | | | | | | ___________________________________________________________________________________ Figure 8-30. Searching Alternate Tables Searching An Array[REV BEG] To search an array, enter the search argument in Factor 1 and use the Resulting Indicators Fields as you would in searching a table. Do not use the Result Field. Unlike with tables, the last element in an array cannot be referenced by using the array name alone; it can, however, be referenced as noted below. Enter the name of the array to be searched in Factor 2. If you use the array name alone, the search begins at the first element of the array. If you use an array name with an index (the index can be a field or a literal), the search begins with the element specified by the index. When the index is a field and the search is successful, the number of the matching array element is placed in the field; otherwise the field is set to 1.[REV END] Example Figure 8-31 shows how to search an array. The LOKUP operation in line 1 searches the array ARR1 (beginning with the element specified by INDX) for an element that matches the field ENTRY3. Assuming that a match is found on the seventy-third element of ARR1, 73 is placed in INDX and indicator 30 is turned ON. The MOVE operation in line 2 is executed since indicator 30 is turned ON. It moves the ARR1 element (found in line 1) to the field STORB. ___________________________________________________________________________________ | | | 1 2 3 4 5 6 7 | | 678901234567890123456789012345678901234567890123456789012345678901234| | _______________________________________________________ | | | | 1 C ENTRY3 LOKUPARR1,INDX 30 | | 2 C 30 MOVE ARR1,INDX STORB | | | | | ___________________________________________________________________________________ Figure 8-31. Searching an Array MHHZO This move zone operation (Move High to High ZOne) moves the zone bits of the high-order position of Factor 2 to the high-order position of the Result Field. Both fields must be alphanumeric. The following illustration shows how this operation works. Z stands for the zone bits of each character and D stands for the digit portion. The shaded area shows the affected characters in the Factor 2 and Result Fields. Factor 2 Field: Result Field: Z D Z D Z D Z D (alphanumeric) ------> Z D Z D Z D Z D (alphanumeric) |---|---|---|---| |---|---|---|---| MHLZO This move zone operation (Move High to Low ZOne) moves the zone bits from the leftmost position of Factor 2 to the rightmost position of the Result Field. Factor 2 must be alphanumeric. The Result Field can be either alphanumeric or numeric. The illustrations below show how MHLZO works. The letter Z stands for the zone portion of the character, D stands for the digit portion, and S stands for the sign portion. The shaded areas show the affected characters in the Factor 2 and Result Fields. Factor 2 Field: Result Field: Z D Z D Z D Z D (alphanumeric) ------> Z D Z D Z D Z D (alphanumeric) |---|---|---|---| |---|---|---|---| Z D Z D Z D Z D (alphanumeric) ------> D D D D D D D S (numeric) |---|---|---|---| |---|---|---|---| MLHZO This move zone operation (Move Low to High ZOne) moves the zone portion of the low-order position of Factor 2 to the high-order position of the Result Field. Factor 2 can be alphanumeric or numeric. The Result Field must be alphanumeric. The illustrations below show how MLHZO works. The letter Z stands for the zone portion of the character, D stands for the digit portion, and S stands for the sign portion. The shaded areas show the affected characters in the Factor 2 and Result Fields. Factor 2 Field: Result Field: Z D Z D Z D Z D (alphanumeric) ------> Z D Z D Z D Z D (alphanumeric) |---|---|---|---| |---|---|---|---| D D D D D D D S (numeric) ------> Z D Z D Z D Z D (alphanumeric) |---|---|---|---| |---|---|---|---| MLLZO This move zone operation (Move Low to Low ZOne) moves the zone bits from the low-order position of Factor 2 to the high-order position of the Result Field. The fields can be either alphanumeric or numeric. The illustrations below show how MLLZO works. The letter Z stands for the zone portion of the character, D stands for the digit portion, and S stands for the sign portion. The shaded areas show the affected characters in the Factor 2 and Result Fields. Factor 2 Field: Result Field: Z D Z D Z D Z D (alphanumeric) ------> Z D Z D Z D Z D (alphanumeric) |---|---|---|---| |---|---|---|---| Z D Z D Z D Z D (alphanumeric) ------> D D D D D D D S (numeric) |---|---|---|---| |---|---|---|---| D D D D D D D S (numeric) ------> Z D Z D Z D Z D (alphanumeric) |---|---|---|---| |---|---|---|---| D D D D D D D S (numeric) ------> D D D D D D D S (numeric) |---|---|---|---| |---|---|---|---| Example Table 8-15 gives examples of how MHHZO, MHLZO, MLHZO, and MLLZO work. In these examples, "--" indicates that the type of move does not apply and _ stands for a blank. Table 8-15. Move Zone Operations ------------------------------------------------------------------------------------------------- | | | | | | Type of Move | Factor 2 | Result Field | Result Field after Move: | | | Contents | before Move | MHHZO MHLZO MLHZO MLLZO | | | | | | ------------------------------------------------------------------------------------------------- | | | | | | Alphanumeric | AH5SR | S51T | B51T S51C K51T | | to | | | S51L | | alphanumeric | | | | | | | | | | Alphanumeric | AH5SR | 12.3 | -- 12.3+ -- | | to | | | 12.3- | | numeric | | | | | | | | | | Numeric to | 852.4+ | 06.282- | -- -- -- | | numeric | | | 06.282+ | | | | | | | Numeric to | 4.7524- | _KD | -- -- _KD | | alphanumeric | | | _KM | | | | | | ------------------------------------------------------------------------------------------------- MOVE [REV BEG] This move operation moves characters from Factor 2 to the Result Field. Characters are moved beginning at the rightmost (low-order) position, continuing to the leftmost (high-order) position.[REV END] If Factor 2 is longer than the Result Field, excess characters are not moved. If Factor 2 is shorter that the Result field, excess characters in the Result Field remain unchanged. You can use this operation to convert an alphanumeric field or constant to packed decimal format. Each alphanumeric character is assumed to be a digit. The zone portion of the low-order alphanumeric character is the sign and it is stored in the low-order position of the Result Field. Zone bits for other characters are stripped and the digits are compressed into packed decimal format. Blanks are converted to zeros. You can also use this operation to convert a packed decimal field to an alphanumeric field. The low-order position of Factor 2 contains the low-order digit and sign. To move data to an array element, enter the array name with index in the Result Field. To duplicate data in every element of an array, enter the array name without an index in the Result Field. You can move one or more zeros or blanks to the Result Field using the figurative constants *BLANK, *BLANKS, *ZERO, or *ZEROS. Table 8-16 gives examples of the combinations of numeric and alphanumeric MOVEs that you can perform. Table 8-16. MOVE Operation Examples ------------------------------------------------------------------------------------------------- | | | | | | Type of MOVE | Factor 2 | Result Field Contents | Result Field Contents | | | Contents | before MOVE | after MOVE | | | | (numeric fields shown in | (numeric fields shown in | | | | hexadecimal format) | hexadecimal format) | | | | | | ------------------------------------------------------------------------------------------------- | | | | | | Alphanumeric to | ABC23 | 1234567 | 12ABC23 | | alphanumeric | | | | | | | | | | Alphanumeric to | 1232E | 1234567C | 1212325C | | numeric | | | | | | | | | | Alphanumeric to | ABC23DEFG | 1234567 | C23DEFG | | alphanumeric | | | | | | | | | | Alphanumeric to | 12323456P | 7654321C | 3234567D | | numeric | | | | | | | | | | Alphanumeric to | ABC23DE | 1234567 | ABC23DE | | alphanumeric | | | | | | | | | | Alphanumeric to | 3212345 | 1234567D | 3212345F | | numeric | | | | | | | | | | Numeric to | 1234567F | ABC23DE | 1234567 | | alphanumeric | 1234567C | AB12CDF | 123456G | | | | | | | Numeric to | 1234567C | 8910123D | 1234567C | | numeric | | | | | | | | | ------------------------------------------------------------------------------------------------- Example Figure 8-32 shows three ways to use the MOVE operation. [REV BEG] Line 1 moves the value 12492 to each element of the array ARY. If the elements of the ARY array were defined as five characters long or more (the size of the value 12492), then the entire value 12492 is moved into the rightmost positions of each element. If the element size is only 1 character, then only the number 2 is moved to each element. (If you want to move 1 to the first element, 2 to the second element, 4 to the third and so on, use the MOVEA operation.) Line 2 shows how to fill an array with zeros, regardless of the number or the size of elements. After the move in line 3, the fifth element of the array contains only blanks. The other elements are unaffected.[REV END] ___________________________________________________________________________________ | | | 1 2 3 4 5 6 7 | | 678901234567890123456789012345678901234567890123456789012345678901234| | _______________________________________________________ | | | | 1 C MOVE 12492 ARY | | C . | | C . | | 2 C MOVE *ZEROS ARY | | C . | | C . | | 3 C MOVE *BLANKS ARY,5 | | | | | | | ___________________________________________________________________________________ Figure 8-32. Using the MOVE Operation MOVEA This move operation moves the Factor 2 Field to the Result Field.[REV BEG] Data is moved beginning at the leftmost (high-order) position, continuing to the rightmost (low-order) position.[REV END] Both fields must be alphanumeric and at least one of them must be an array. Do not use the same array for both the Factor 2 and Result Fields. MOVEA lets you: * Move contiguous elements from one array to contiguous elements of another. * Move contiguous array elements to a single field. * Move a single field to several contiguous array elements. When you enter an array element in Factor 2, it is the first field that is moved. Subsequent elements are moved until the last array element is moved or filled, or until all of the characters in the shorter field are moved. Depending on the length of the Factor 2 and Result Fields, MOVE may end in the middle of a field or array element. If Factor 2 is longer than the Result Field, excess characters in Factor 2 are not moved. If Factor 2 is shorter than the Result Field, excess characters in the Result Field remain unchanged. When you use a figurative constant (*BLANK, *BLANKS, *ZERO, or *ZEROS) in Factor 2 and an array name in the Result Field, the array is filled with blanks or zeros. If the array is indexed, the operation begins with the element corresponding to the index number and continues to the end of the array. MOVEL This move operation moves Factor 2 to the Result Field.[REV BEG] Data is moved beginning at the leftmost (high-order) position, continuing to the rightmost (low-order) position.[REV END] You can use the figurative constants *BLANK(S) and *ZERO(S) in the Factor 2 Field. If Factor 2 is longer than the Result Field, the excess low-order characters are not moved. If Factor 2 is shorter than the Result Field, excess characters in the Result Field remain unchanged. You can use this operation to convert an alphanumeric field or constant to a number by moving it to a numeric field. The alphanumeric field must contain ASCII digits (except in the low-order position). The digit portion of each character is converted to the corresponding number before it is moved. When the number of characters in the alphanumeric field equals or exceeds the number of digits in the Result Field, the sign of the alphanumeric field is moved to the low-order position of the Result Field. Zones are stripped from the other characters, and the numeric equivalents are saved in packed decimal format. You can also use MOVEL to convert a numeric field or a constant to an alphanumeric value by moving it to a alphanumeric field. Each digit is converted to its corresponding ASCII character. If the entire field is moved and the sign is negative, the rightmost zone and digit bits are converted to one character. MSG This display operation retrieves a message from a User Message Catalog file (created by the Native Language Support, NLS or by MAKECAT) and places it in the field that you specify. You may want to use MSG to tailor corporate report headings contained in a User Message Catalog, for example, to fit a particular division's requirements. The name of the User Message Catalog file is CATALOG and it is assumed to be in your logon group and account. If you want to use another file or if CATALOG is in another group or account, enter an operating system :FILE command to change these values. For example, the command :FILE CATALOG=MYMSG.PUB.PAYROL specifies that the file MYMSG is the User Message Catalog and it is located in the PUB.PAYROL group and account. You can use only one User Message Catalog file in a program. As a result, if you're using MSG and the message features of the RPG Screen Interface, (RSI) combine all messages into one file. To use MSG, enter the identification number of the message in the Factor 1 Field. You can enter a literal or alphanumeric field. The message identification consists of a message number and, optionally, a set number. The message identification has the format, nnnn[:ss] where nnnn is the message number and ss is the set number. The colon (:) is used to separate the two numbers. If you omit the set number, the first set is used. In the Result Field, enter the name of the field where you want to store the message. You can use an alphanumeric field or array. If the message exceeds the length of the Result Field, the low-order characters are truncated. The maximum length of a message is 256 bytes. Enter the indicator in the High Subfield (columns 54-55) that you want turned ON when the message cannot be retrieved. If you do not enter an indicator in this field and the message cannot be retrieved, the H0 indicator is turned ON. Do not use the Factor 2, Decimal Positions, Half Adjust, and the Low and Equal Subfield Fields. Example Four examples of valid message identifications are shown in Table 8-17. See the DSPLM operation for examples of how to code message identifications. Table 8-17. Valid Message Identifications ----------------------------------------------------------------------------------------------- | | | | | Message Identification: | Message Number: | Set Number: | | | | | ----------------------------------------------------------------------------------------------- | | | | | | 12 | 1 (default) | | "12" | | | | | | | | | 3 | 1 (default) | | "3." | | | | | | | | | 32 | 6 | | "32:6" | | | | | | | | | 4 | 2 | | "0004:02" | | | | | | | ----------------------------------------------------------------------------------------------- MULT This arithmetic operation multiplies Factor 1 by Factor 2 and places the product in the Result Field. Be sure that the Result Field is large enough to hold the largest possible result. Excess digits are truncated. If Factor 1 is blank, the Result Field is multiplied by Factor 2 and the product is placed in the Result Field. MVR This arithmetic operation moves the remainder from the previous DIV operation to the Result Field. Use MVR immediately following the DIV operation and condition it with the same indicators (see figure 8-15). Do not use the Factor 1 or Factor 2 Fields. The remainder is stored as a decimal number. When you define the field entered in the Result Field, make sure that it contains the same number of whole number positions as the Factor 2 Field of the DIV operation. If must also contain the number of decimal positions which is the greater of: * The number of decimal positions in Factor 1 of the DIV operation. * The sum of the decimal positions in the Factor 2 and Result Fields of the DIV operation. PARM This external subroutine operation passes data to an external subroutine. PARM is used in conjunction with EXIT. Enter a PARM operation for each data element that you want to pass to the subroutine. Begin the PARM operations immediately after the EXIT operation that calls the subroutine. Enter the data element to be passed in the Result Field. You can enter a field, table, or array name. Do not enter an indicator. Data elements are passed as byte arrays in the same order you enter them in the PARM operations. Leave the Factor 1 and Factor 2 Fields blank. Example Figure 8-33 shows how to use the EXIT operation to call an external subroutine and how to use the PARM operation to exchange information with it. The RPG program reads two numbers (FLD1 and FLD2) and a six-character string (FLD3) from the terminal. It then calls the external subroutine EXSUB in line 1. EXSUB is written in COBOL and is shown in figure 8-34. It adds the fields passed to it as parameters (FLD1 and FLD2 starting in line 2) and displays the result. The result (RESLT1) along with FLD1 and FLD2 are returned to the RPG program when EXSUB finishes. The second external subroutine EXSUB2 is then called in line 3. EXSUB2 is written in C and is shown in figure 8-35. The field FLD3 is passed to it as a parameter at line 4. EXSUB2 moves FLD3 to the field RESLT2 and returns to the RPG program. The RPG program writes the input fields (FLD1, FLD2) and the fields created by the external subroutines (RESLT1 and RESLT2) to the output file OUTFLE. ___________________________________________________________________________________ | | | 1 2 3 4 5 6 7 | | 678901234567890123456789012345678901234567890123456789012345678901234| | _______________________________________________________ | | | | FTERMIN IDE V 14 | | FOUTFLE O F 50 DISK | | | | ITERMIN AA 01 1 CO | | I 3 80FLD1 | | I 9 140FLD2 | | I 15 20 FLD3 | | | | C READ TERMIN LR | | 1 C NLR EXIT EXSUB | | 2 C PARM FLD1 | | C PARM FLD2 | | C PARM RESLT1 70 | | 3 C NLR EXIT EXSUB2 | | 4 C PARM FLD3 | | C PARM RESLT2 6 | | | | OOUTFLE D 01 | | O 5 "FLD1=" | | O FLD1 11 | | O 17 "FLD2=" | | O FLD2 23 | | O 31 "RESULT=" | | O RESLT1 38 | | O 44 "FLD3=" | | O RESLT2 50 | | | | | | | ___________________________________________________________________________________ Figure 8-33. Using EXIT, PARM and External Subroutines _____________________________________________________________________________ | | | $CONTROL SUBPROGRAM | | IDENTIFICATION DIVISION. | | PROGRAM-ID. EXSUB. | | ENVIRONMENT DIVISION. | | DATA DIVISION/ | | LINKAGE SECTION. | | * | | *NUMERIC PARAMETER DATA TYPED AS COMP-3 | | * | | 01 FLD-1 PIC S9(6) COMP-3. | | 01 FLD-2 PIC S9(6) COMP-3. | | 01 RESULT PIC S9(7) COMP-3. | | PROCEDURE DIVISION USING FLD-1 FLD-2 RESULT. | | START-LINK. | | ADD FLD-1 FLD-2 GIVING RESULT. | | DISPLAY "FLD-1= " FLD-1 " FLD-2 " FLD-2 " RESULT= " RESULT.| | GOBACK. | | | | | | | _____________________________________________________________________________ Figure 8-34. The External Subroutine EXSUB Written in COBOL _____________________________________ | | | exsub2 (A,B) | | char *A; | | char *B; | | { | | strncpy (b, a, 6); | | } | | | | | _____________________________________ Figure 8-35. The External Subroutine EXSUB2 Written in C