This procedure returns the ordering information for the input text. The ordering information determines how the input text is collated. It includes the ordering and priority sequence values of the characters and any substitution of characters to be made when the input text is sorted.

One of the following types of ordering information can be chosen:

Example

This example obtains the ordering sequence values and priority sequence values for an input text string. The ccsversion is CanadaEBCDIC. The MultiLingual System Administration, Operations, and Programming Guide can be used to determine that the ccsversion number for CanadaEBCDIC is 74. This number can also be retrieved by calling VALIDATE_NAME_RETURN_NUM with the name CanadaEBCDIC. This example requests logical ordering information, so that both the OSVs and PSVs are returned. This example allows for maximum substitution, so the parameter MAX_OSVS is equal to (ITEXT_LEN * 3) and TOTAL_STORAGE is equal to INTEGER(MAX_OSV/2).

BEGIN

 $ INCLUDE INTL="SYMBOL/INTL/ALGOL/PROPERTIES." 10000000 - 49999999

  DEFINE SOURCE_START = 0 #
       ,DEST_START = 0 #;

  FILE OUT(KIND=DISK,UNITS=CHARACTERS,FILEUSE=IO,FILETYPE=0,NEWFILE,
           MAXRECSIZE=80,TITLE="OUT/ALGOL/VSNGETORD_ONE_TEX.");
  EBCDIC ARRAY SOURCE[0:25]
             ,DEST[0:25];
  INTEGER VSN_NUM
        ,ITEXT_LEN
        ,MAX_OSVS
        ,TOTAL_STORAGE
        ,RESULT;

  VSN_NUM := 74;
  ITEXT_LEN := 5;
  MAX_OSVS := ITEXT_LEN * 3;
  TOTAL_STORAGE:= MAX_OSVS + INTEGER(MAX_OSVS/2);
  REPLACE SOURCE[0] BY "ABC»«";
  RESULT:=VSNGETORDERINGFOR_ONE_TEXT(VSN_NUM, SOURCE, SOURCE_START,
            ITEXT_LEN, DEST, DEST_START, MAX_OSVS, TOTAL_STORAGE,
            CS_LOGICALV);
  WRITE(OUT,<"RESULT = ",J4>,RESULT);
  IF RESULT EQL CS_DATAOKV THEN
     WRITE(OUT,<"DEST   = ",A25>,DEST);
  CLOSE(OUT,LOCK);
END.

Output

RESULT = 1
DEST = 414243414541 450000000000 000000111221 100000000000

VSN_NUM is an integer passed to the procedure. It contains the number of the ccsversion that is used.

SOURCE is an array passed to the procedure. It contains the text for which the ordering information is requested.

SOURCE_START is an integer passed to the procedure. It contains the offset of the location where the source text is to begin.

ITEXT_LEN is an integer passed to the procedure. It contains the length of the source text.

DEST is a result returned by the procedure. It contains the ordering information for the source text.

DEST_START is an integer returned by the procedure. It designates the starting offset at which the result values are placed.

MAX_OSVS is an integer passed to the procedure. It designates the maximum number of bytes to be used to store the ordering sequence values.

The value of MAX_OSVS should be at least the length of the input text, but it might need to be greater to allow for substitution. The maximum substitution length is 3 bytes; therefore, to allow for substitution for every character, the value of MAX_OSVS is as follows:

<length of source text in bytes> * 3

If the number of ordering sequence values returned is less than MAX_OSVS, then the array row is padded with the ordering sequence value for blank.

TOTAL_STORAGE is an integer passed by the procedure. It defines the maximum number of bytes needed to store the complete ordering information for the text. If equivalent ordering information is requested, TOTAL_STORAGE is equal to MAX_OSVS. If logical ordering information is requested, space must be provided for the four-bit priority values in addition to the space allowed for the OSVs. Each OSV has one PSV, and one byte can hold two PSVs. Therefore, the space allowed for PSVs is MAXOSVS/2, and the value of TOTAL_STORAGE is as follows:

MAXOSVS + (MAXOSVS/2)

When the ordering information is returned by the procedure, all the OSVs are listed first, followed by all the PSVs.

CS_LOGICALV represents an integer that requests logical ordering information. It is one of two options:

RESULT is an integer returned by the procedure. It indicates whether or not an error occurred during the execution of the procedure. An explanation of the error result values and messages can be found at the end of this section. The values returned by this procedure include: