• Topics
  • Definitions
  • Pointers
  • Instructions
    • MOVE
    • RESET
    • SETLPTR
    • LENSET
    • MOVELPTR / MOVEFPTR
    • COUNT
    • CLEAR
    • SCAN
    • SPLICE
    • PACK / PACKKEY
    • UNPACK
    • WHEREIS / WHEREISLAST
  • Null Strings
  • Other Instructions
  • Example Code
• See also
  • Edit Text
  • INDEX

FIRST_NAME   DIM    30
LAST_NAME    DIM    30
CITY         DIM    20
STATE        DIM     2
ZIP          DIM    10

             123456789.123456789.123456789.123456789.
NAME  INIT  "Mid-Michigan Computer Consultants"
                 ^               ^
                 FP              LP

       "Michigan Computer"

               123456789.123456789.123456789.123456789.
NAME     INIT  "Mid-Michigan Computer Consultants"
                    ^               ^
                    FP              LP
WORKNAME DIM   30
			
         MOVE  NAME TO WORKNAME
.... after the move workname will be:
               123456789.123456789.123456789.
              "Michigan Computer"
               ^               ^
               FP              LP		 

               123456789.123456789.123456789.123456789.
NAME     INIT  "Mid-Michigan Computer Consultants"
                    ^               ^
                    FP              LP
WORKNAME INIT  "This is the original data in workname"
         MOVE  NAME TO WORKNAME
.... after the move workname will be:
               123456789.123456789.123456789.
              "Michigan Computer"
               ^               ^
               FP              LP		 

• MOVE: Obviously, this is the most commonly used string instruction. It's probably the most commonly used period!
  
  Move is as simple as MOVE A TO B. But there are several useful variations. The most powerful thing about MOVE is that it will automatically handle many type conversions automatically. Move a STRING to a NUMBER automatically converts formats.
  
  The Sunbelt manuals do a good job of defining the MOVE operations. Still there are a few things to keep in mind.
  
  
  • Only the LOGICAL strng from the sending field is moved. That is, from form pointer through length pointer.
    
    
  • The sending data is put into the receiving field starting at the first physical byte and the receiving field length pointer becomes the number of bytes sent.
    
    
  • If the sending field is NUL (no length) then nothing is moved and the receiving field is not changed. That's important. Consider the example:

         WORK_NAME    DIM     10
         LIVE_NAME    INIT    "This is the Name"
                      KEYIN   "Enter a name:",WORK_NAME
                      MOVE    WORK_NAME,LIVE_NAME
    

    If the user just taps ENTER the variable WORK_NAME will have no data. It will be nul. The MOVE will do nothing. That means that where you might expect LIVE_NAME to become nul after the move, in truth there is no change at all!
    
    To pretect yourself if this is a possibility, you can clear the contents of LIVE_NAME in one of several ways PRIOR to the move. (See NUL strings and UNPACK).
  
  
  
  
• RESET: Sets the FORM POINTER for the string. This is how you say where the sub-string starts.
  Consider the following:

        NAME     DIM    30
                 MOVE   "John and Mary Doe",NAME
                 DISPLAY *HON,*LL,NAME,*PL,*HOFF
                 RESET  NAME,10
                 DISPLAY *LL,NAME,*PL         
  

  In this example moving the string "John and Mary Doe" fills the entire string and leaves the form pointer at the first byte (1). The DISPLAY shows the entire string.
  
  The RESET NAME,10 changes the form pointer to 10. This means that the logical string is position 10 through the length pointer. The second DISPLAY will show Mary Doe.
  
  If you leave out the number and just say "RESET NAME", the FORMPONTER is set to 1.
  
  RESET cannot extend the PHYSICAL length of the string, but it can extend the LOGICAL LENGTH. Try this example:

   NAME     DIM    30
            MOVE   "John and Mary Doe",NAME   //initialize
            DISPLAY *HON,*LL,NAME,*PL,*HOFF   //show contents
            MOVE   "JERRY",NAME               //change contents
            DISPLAY *HON,*LL,NAME,*PL,*HOFF   //show contents
            RESET  NAME,10                    //point to byte 10
            DISPLAY *LL,NAME,*PL              //display logical string
            RESET  NAME                       //point back to byte 1
            DISPLAY *LL,NAME,*PL              //show logical string
  

  MOVE "John and Mary Doe",NAME puts 17 characters into the string. The form pointer is 1 and the length pointer is 17. The physical length remains 30; that's the maximum number of bytes the string can hold.
  
  MOVE "JERRY",NAME puts 5 characters into the string. The FP is 1 and the LP is 5 so the locigal string is just JERRY. The physical length remains 30.
  
  Here's the trickie part:  
  RESET NAME 10 Makes the form pointer 10. It must ALSO extend the logical length to 10. The logical string is byte 10 to 10. What's important is that the MOVE "JERRY",NAME did not erase anything from the original contents of the string. The physical contents of the string have become JERRYand Mary Doe. The display of the logical string will get the byte at position 10 or M.
  
  Finally, RESET NAME, where no number is given, puts the form pointer back to byte 1. The length pointer remains at 10. The logical string becomes: JERRYand M".
  
  
  (NOTE:    The examples use DISPLAY to show the results. When running PLBWIN under windows, be certain that the program includes a WINSHOW instruction to turn on the main window.
  
  The "*LL" in the DISPLAY statement indicates that only the Logical Length should be displayed. The "*PL" restores the DISPLAY to say that the physical length should be shown. The "*HON" and "*HOFF" turn on high intensity or reverse video. That makes it very obvious on the screen just what the displayed string really is:
  
  
  
• SETLPTR:     (See RESET above)
  Sets the LENGTH POINTER for the string. This is how you say where the sub-string ends. If, for example, you want the substring starting at position 5 and ending at 10 you can code
       RESET NAME to 5
       SETLPTR NAME to 10
  
  
• LENSET: Is another way to set the LENGTH POINTER for the string. In this case, the length is set to the current value of the FORM POINTER. There are many ways to set the FORM POINTER and many times you don't need to know the actual value, you just want to set the length to wherever you're currently pointing. The most direct example of this could be as follows:

        RESET     NAME to 20    ;point to position 20
        LENSET    NAME          ;set length to current position
        RESET     NAME          ;point back to position 1
  

  Another example could be used to parse strings. Assume the string contains city and state separated by a comma and you want to just show the city. You could do this:

  CITY  INIT  "Bay City, Michigan"
        DISPLAY *HON,*LL,CITY,*PL,*HOFF     //show logical string (everything)
        SCAN    ",",CITY                    //position form pointer to ,
        BUMP    CITY,-1                     //back up 1 byte
        LENSET  CITY                        //limit the length here
        RESET   CITY                        //position form pointer to 1
        DISPLAY *HON,*LL,CITY,*PL,*HOFF     //show new logical string
  

  
  
  
• MOVEFPTR and MOVELPTR: These two instructions allow you to get the current values of a string's FORM POINTER and LENGTH POINTER. These numbers can be very useful.

  STRING  INIT    "Bay City, Michigan"
  NWK_FP  FORM    3                             ;work variable for form pointer
  NWK_LP  FORM    3                             ;work variable for length pointer
          MOVEFPTR    STRING TO NWK_FP          ;Get the form pointer
          MOVELPTR    STRING TO NWK_LP          ;Get the length pointer
          DISPLAY     "Sub string ":
                      *HON,*LL,STRING,*PL,*HOFF;
                   *N,"The sub-string starts at ",NWK_FP:
                      " and ends at ",NWK_LP
  

• COUNT: This instruction "determines the number of keystrokes that might typically be required to re-enter the data currently existing in a variable or list of variables". What that effectively does is to give the length of a string but truncating trailing spaces!
  
  This is a sleeper instruction. It's far more useful than it might seem. We use it for truncating strings which might have trailing spaces.
  
  Trailing spaces in a string can be a nusiance... and you get those trailing spaces in a string in many ways... like reading a person's name from a file where the field is long but the person's name is short.
  
  
  • You can move a string to a number and get automatic conversion. For this to work, the data in the string must be a valid number AND it cannot have trailing spaces.
    
    
  • If you use the *EDIT qualifier in a KEYIN instruction, the user can tap the END key and have the cursor jump to the logical end of the string. If there are trailing spaces, they are part of the length and the END key jumps to the last space, not the last letter. This is also true in the GUI world.
  
  
  We use the following code for truncating strings. The TRUNCATE routine is built into our standard MMCCSERV.PLS INCLUDE code that becomes part of every program:

                CALL    TRUNCATE USING CITY
                    ...........
  
     #TRUNCATE_STRING  DIM  ^                       //pointer variable 
     #TRUNCCATE_LEN    FORM 4                       //truncated length of string
     truncate  LROUTINE  USING #TRUNCATE_STRING
               COUNT     #NWK04,#TRUNCATE_STRING    //get string's truncated length
               SETLPTR   #TRUNCATE_STRING, #NWK04   //set the string's length
               RETURN                               //return  to caller
  

  
  
• CLEAR:    Sets both the FORM POINTER and the LENGTH POINTER to zero.
  
  This gives the field no aparrent value. The string is effectively NUL.
  
  HOWEVER the original contents of the string are not erased. Those contents can be easily recovered by simply resetting the FORM and LENGTH pointers.
  
  A truly nul string has a logical length of zero but also contains no data. See the section on NUL STRINGS below.
  
  
• SCAN: This very powerful instruction can be used to locate any value within a string. For example:

           SCAN "HOT" IN WORK_STRING
  

  If the scan succeeds and finds the desired string, the target string's FORM POINTER is set to the first byte of the string being looked for. Assume, in the example above, that WORK_STRING contains

           "THE WEATHER IS HOT AND DRY"
            123456789.12345679.123456789.
  

  After the SCAN for "HOT" the FORM POINTER in WORK_STRING will be set to 16, the position of the sub-string "HOT".
  
  The SCAN operation starts at the current FORM POINTER position and proceeds to the right. This allows for progressive scanning. Find the first occurrance of a word, then the next, then the next, etc.
  
  If the desired string is FOUND, the EQUAL flag is set ON. If not found, EQUAL is off.
  
  Here's a practical routine that illustrates what could be done. We want to find each occurance fo the word HOT in the string.

  WORK_STRING  INIT        "THE DAY WAS HOT, HOT, HOT AND DRY"
  NWK_FP       FORM        2
  
               DISPLAY     "Find all occurances of the word HOT in ":
                           *HON,*LL,WORK_STRING,*PL,*HOFF
               LOOP
                 SCAN      "HOT" IN WORK_STRING      //Find next HOT
                 BREAK IF NOT EQUAL                  //nothing found
                 MOVEFPTR  WORK_STRING, NWK_FP       //retreive form pointer
                 DISPLAY   "HOT fount at byte ",NWK_FP
                 BUMP      WORK_STRING               //jump past current HOT
               REPEAT UNTIL EOS
               DISPLAY     "There are no more occurances of HOT"
               RESET       WORK_STRING
  

  NOTE: Pay particular attention to the BUMP at the end of the loop. The SCAN starts at the current form pointed byte and works to the right. It stops on the next occurance of the desired string and leaves the form pointer at the first byte of that string. If we scan again, from that position, the SCAN will change nothing and the routine will be in an infinite loop.
  
  The BUMP insures that we move past the current HOT before scanning again.
  
  The REPEAT UNTIL EOS after the BUMP covers us in the event that we're scanning for a single letter (rather than a word like HOT) and the string ends with that letter. BUMP, when sitting on the last byte of the string, sets the EOS flag but it does NOT change the current formpointer. Without this test, we have another potential infinite loop.
  
  
• PACK and PACKKEY:
  
  These two instructions are used, as the work "pack" implies, to pack many variables into a single string.
  
  PACK is a string instruction in that the receiving field must be a string. The sending fields, however, can be almost any type of variable. PL/B will make the necessary conversions if one of the input variables is not a string.
  
  There are many, many uses for PACK. A simple one might be to make up a CITY, STATE, ZIP string from individual parts:

      CITY         DIM    30
      STATE        DIM     2
      ZIP          DIM    10
  
                   PACK   PRINT_CITY WITH CITY, ", ", STATE, " ",ZIP
  

  
  You can use continuation lines to make the pack more readable:

                   PACK   PRINT_CITY WITH:
                            CITY:
                            ", ":
                            STATE:
                            " ":
                            ZIP
  

  PACK works on the LOGICAL string. In the above example, if the string CITY is 30 bytes and contains only the 8 byte string Bay City, that is all that will be packed.
  
  The corolary of that is that if the string is full length as it might be after reading CITY from a file, then PACK will produce a resulting string like:

                  "Bay City               , MI 48706"
  

  This is a good place to use the COUNT instruction and the TRUNCATE routine to insure the string is truncated.
  
  There are times, however, when you WANT to have the full string guaranteed. When packing an indexed file key, for example. Consider the following:

      ISI_KEY      DIM  14
      COMPANY      DIM  10
      ACCT_ID      FORM  4
                   PACK  ISI_KEY,COMPANY,ACCT_ID
  

  Suppose that the user enters "MMCC" as the COMPANY and "25" as the ACCT_ID. The COMPANY string is only 4 bytes long. The result of the PACK would be:

          "MMCC  25"
  

  When the desired string is:

          "MMCC        25"
  

  In that example, the "25" works fine because it is a numeric variable. By definition it is right justified and space filled. The PACK instruction gets it right.
  
  But the COMPANY_ID field is a string and pack only uses the LOGICAL string... 4 bytes!
  
  PACKKEY was designed just for this circumstance. PACKKEY used the physical length of all variables and SPACE FILLS any variables where the logical length is shorter than the physical length. So in this case, PACKKEY would change the short "MMCC" to "MMCC      ".
  
  Another technique method of ensuring the full length of a string is a useful variation of PACK: packing variable into itself. To achieve a full length variable one could use the instruction:

           PACK   COMPANY,COMPANY,"                        "
              or
           PACK   COMPANY,COMPANY, SPACES      //assuming SPACES is defined
  

  INCREMENTAL Packing is another useful technique. You initialize a string then PACK it with some data. As more data is developed, you pack the string with itself plus the additional data. This is similar to using APPEND to build up a string, but this one is more flexible.

  TITLE_LINE   DIM   1500                 //working string
  HEX_7F       INIT  0x07,0xFF            //new line in an EditText
  WORK40       DIM   40                   //general work area
  
               UNPACK   NUL, TITLE_LINE   //empty the string
  
               GETITEM  F1_ET_Name,0,WORK40      //Get name
               PACK     TITLE_LINE,TITLE_LINE:   //pack into itself
                            WORK40               //append WORK40
  
               GETITEM  F1_ET_Addr,0,WORK40      //Get address
               PACK     TITLE_LINE,TITLE_LINE:   //pack into itself
                            HEX_7F:              //new line
                            WORK40               //append WORK40
  
               GETITEM  F1_ET_City,0,WORK40      //Get city
               PACK     TITLE_LINE,TITLE_LINE:   //pack into itself
                            HEX_7F:              //new line
                            WORK40               //append WORK40
  

  The above example may seen awkward. One could simply GETITEM into three fields and pack using a single instruction. The usefulness may be more obvious is we make the GETITEM and PACK into a ROUTINE:

                 CALL    PACK_IT_UP USING TITLE_LINE, F1_ET_Name
                 CALL    PACK_IT_UP USING TITLE_LINE, F1_ET_Addr
                 CALL    PACK_IT_UP USING TITLE_LINE, F1_ET_City
                        ............................
  
  PASSED_ET      EDITTEXT   ^
  PASSED_STRING  DIM      ^
  pack_it_up     ROUTINE  PASSED_STRING, PASSED_ET
                 GETITEM  PASSED_ET,0,WORK40       //Get ET data
                 PACK     TITLE_LINE,TITLE_LINE:   //pack into itself
                              HEX_7F:              //new line
                              WORK40               //append WORK40
                 RETURN
  

• UNPACK:     This is obviously the opposite of PACK. UNPACK takes any string and splits it's data into multiple fields based on the size of the receiving fields:

          UNPACK   INPUT_STRING INTO FIELD1, FIELD2, FIELD3, etc.
  

  Unlike PACK, the UNPACK does not know the logical lengths of the elements it is dealing with. As many bytes are moved from the input field to each of the receiving fields as needed to fill each of those fields.

  RAW_STRING   INIT    "123,456,789,MMCC"
  FIELD1       FORM    3
  FIELD2       DIM     4
  FIELD3       FORM    3
  FIELD4       DIM    50
               UNPACK  RAW_STRING INTO FIELD1, FIELD2, FIELD3, FIELD4
  

  In the above example:
  • FIELD1 becomes 123 because the first 3 bytes are good numbers
  • FIELD2 becomes ,456 which are the next bytes
  • FIELD3 becomes 0 because it is a number and the next 3 bytes start with a comma which means it is not a valid number.
  • FIELD4 becomes 9,MMCC because the previous field required 3 bytes even though those three were not a valid number. FIELD4 is filled to the right with spaces.
  
  The subject of an UNPACK can be a RECORD, VARLIST, LIST, or any similar structure. that means the above example could be:

  RAW_STRING   INIT    "123,456,789,MMCC"
  MY_LIST   LIST
  FIELD1       FORM    3
  FIELD2       DIM     4
  FIELD3       FORM    3
  FIELD4       DIM    50
            LISTEND
               UNPACK  RAW_STRING INTO MY_LIST
  

NUL         INIT    1
FIELD       INIT   "This is a dummy string"
            UNPACK NUL,FIELD        //completely clears FIELD

• You cannot MOVE a nul string to another string. Nothing will happen.
           MOVE NUL to NAME
  That MOVE does nothing and the value of NAME is unchanged.
  
  
• A string that contains any data, including one or more spaces is NOT nul.
  
  
• A nul string can be used in an UNPACK instruction to clear everything in the receiving string.
           UNPACK NUL,TITLE_LINE
  
  

 NAME INIT     "MMCC, Inc."             //normal string with contents
      CLEAR    NAME                     //Set form and length pointers to zero
      DISPLAY  "name:":                      
               *HON,*LL,NAME,*PL,*HOFF  //shows nothing 
      RESET    NAME,3                   //point to byte 3 (extend length to match)
      DISPLAY  "name:":                      
               *HON,*LL,NAME,*PL,*HOFF  //shows "C"
      RESET    NAME                     //point to byte 1 (don't change length)
      DISPLAY  "name:":                      
               *HON,*LL,NAME,*PL,*HOFF  //shows "MMC"

• RIGHT justifying
• Replace 1 byte with a string
• Replace one STRING with another string.
• REMOVE one btye from current position
• STUFF a test string into the left end
• PACKUP the integers in a string.
• INSERT a test string into the middle.
• PUSH into a string to show. Use it like a PUSH STACK.
• COMPRESS a report line as used in ODA-M012. Coule be any similar line.

..................
.      Remove all opening boxes [
.      
        FOR     IX3 FROM 1 TO 50      ;artificial killer    
          SCAN  "[",RAW_DATA          ;find next [
          IF NOT EQUAL                ;none left        
                BREAK
          ENDIF
            
          SPLICE  "",RAW_DATA,ONE     ;remove 1 byte
          RESET   RAW_DATA            ;back to front
        REPEAT                        ;see if any more

[label]  WHEREIS     {source}{sep}{search} [{sep2}{result}]
[label]  WHEREISLAST {source}{sep}{search} [{sep2}{result}]

• The {source} and {search} variables are not changed by the operation of this instruction.
  
  
• The EOS flag is set TRUE if the {source} or {search} is NULL.
  
  
• The ZERO flag is set FALSE when the {source} string is found in the {search} variable. If the optional {result} variable is specified, the form pointer value of the located string is stored. The ZERO flag is set TRUE if the {source} string is not found in the {search} string.
  
  
• WHEREIS searches in a forward order.
  
  
• WHEREISLAST (added in runtime version 9.1.C) seaches backward.
  
  
• The OVER flag is set TRUE if {result} is too small to receive the form pointer value.

AND	Bitwise AND two characters together.
APPEND	Append a string to another string.
BUMP	Add one to the Form Pointer.
CHOP	Move a variable to another while removing trailing spaces.
CLEAR	Set Form Pointer & Length Pointer to zero.  Moves zero to numeric field.
CMATCH	Match a character with another character.
CMOVE	Move a character.
COUNT	Count number of characters in a list of variables.
EDIT	Apply a special display format to a character variable.
ENDSET	Set the Form Pointer equal to Length Pointer.
EXTEND	Append one or more blanks to a string.
FILL	Fill character variables with a value.
FINDCHAR	Search a string for a character from a list.
LCMOVE	Move the Length Pointer character to a variable.
LENSET	Set the Length Pointer equal to Form Pointer.
LOAD	Move one of several variables to another variable.
LOWERCASE	Convert a string to lower case.
MATCH	Match a variable with another variable.
MOVEFPTR	Move the Form Pointer value to a numeric variable.
MOVELPTR	Move the Length Pointer value to a numeric variable.
MOVELS	Move a variable to another variable respecting the Logical String.
MOVEPLEN	Move the Physical Length value to a numeric variable.
MOVEPTR	Move a pointer variable to another pointer variable.
NOT	Bitwise NOT a character and move to another variable.
OR	Bitwise OR a character with another character.
PACK	Append several variables to another variable.
PACKKEY	Append several variables to another variable respecting Physical Length.
PARSE	Select next several characters based on a mask.
PARSEFNAME	Retrieve a filename from within a string.
REMOVE	Move a variable to another variable and adjust the Form Pointer of first variable.
REPLACE	Change characters to other characters in a character string.
RESET	Set the Form Pointer of a string variable.
SCAN	Search a variable for a character string.
SDELETE	Delete several characters from a character string.
SEARCH	Search a set of variables for starting with a character string.
SET	Assigns a variable or list of variables to a value of one.
SETLPTR	Set the Length Pointer of a string variable.
SFORMAT	Change the Physical Length value of a string variable.
SINSERT	Inserts a string variable into another string variable.
SMAKE	Create a string variable.
SPLICE	Replace logical contents of one variable with another.
SQUEEZE	Move a variable to another while removing characters.
STORE	Move a variable to one of several variables.
TEST	Bitwise test one character with another character.
TYPE	Determine if a string variable has a valid numeric format.
UNPACK	Split a variable to several (usually smaller) variables.
UPPERCASE	Convert a string to upper case.
XOR	Bitwise exclusive or one character with another character.

FLD1   DIM 20
FLD2   DIM 20
       MOVE "ABCDEFG",FLD1
       ENDSET FLD1
       LOOP UNTIL EOS
         CMOVE FLD1, FLD2
         BUMP  FLD1, -1
       REPEAT

FLD1   DIM 20
       MOVE "ABCDEFG.INI",FLD1
       ENDSET FLD1
       BUMP FLD1,-3
       MATCH ".INI",FLD1
       IF EQUAL
	     ...... do something ....
       ENDIF

       scan    ".ini",string
       if equal
           I found it
         else
           it's not there
       endif
       reset   string

.   For the reverse order:
input  dim 12   ; assume large enough for data
output dim 12
xn     form 2   ; array pointer
aa     dim 1(12)

       unpack  input, aa     ;array elements up to 12
       count   xn,    input  ;number of bytes input
       loop
         append aa(xn), output  ;begins with "last" character in array 
         decr xn
       repeat until (xn=0)
       chop output

input   dim 12    ;assume large enough for data
output  dim 12
aa      dim 1(12)
        unpack input,aa     ;array elements up to 12
        pack output with aa(12),aa(11),aa(10),aa(9),aa(8):
                         aa(7), aa(6), aa(5), aa(4),aa(3):
                         aa(2), aa(1)

       MOVELPTR  #strSource,#lngSourceFptr
       UPPERCASE #STRSOURCE
       WHEREISLAST ".INI" IN #STRSOURCE GIVING POSITION

#strSource DIM ^300