Google
 

Trailing-Edge - PDP-10 Archives - BB-W661B-BM_1984 - tools/glxtxt.mem
There are no other files named glxtxt.mem in the archive.
   MACROS AND PSEUDO-INSTRUCTIONS


   2.17  $TEXT Pseudo-instruction

   These pseudo-instructions  perform  various  utility  functions.   The
   operations  are  in  many  cases  fairly complicated and although they
   behave as pseudo-instructions they may in reality be subroutine calls.

   The $TEXT pseudo-instruction provides a facility for formatting  ASCII
   strings.   This  facility  includes  a mechanism which allows imbedded
   variables in the strings which may be decoded into ASCII from a number
   of internal forms (decimal, sixbit, date and time etc.).

   The $TEXT instruction takes two arguments.  The first is  usually  the
   address  of  a  subroutine  (called  the Text Output Routine) which is
   called with each decoded character.  This allows the user the  ability
   to  completely  control  the  destination  of the decoded string.  The
   routine is called with the character in accumulator S1.   See  section
   2.17.4  for  a description of the rules and conventions concerning the
   Text Output Routine.  There is one $TEXT  subroutine  built  into  the
   library  for  output to the job's terminal.  See the section on GLXTXT
   subroutines for a description of this routine.

   One of the arguments in the program's Initialization Block (IB) is the
   name of a default $TEXT routine.  If $TEXT is called with a null first
   argument, the routine specified in the IB is used.

   Another alternative for the first argument to $TEXT is  an  expression
   of  the  form  "<-1,,adr>".   On the $TEXT call this is converted to a
   byte pointer of the form "POINT 7,adr" and each byte is deposited with
   that byte-pointer.

   The second argument to $TEXT is the string  to  decode.   The  overall
   format of the call is:

                     $TEXT(ROUTINE,<string to decode>)

   The string to decode may simply be an ASCII string to print or it  may
   be  a  complex  format  specification  using  imbedded  parameters  as
   described in the following section.  An example  of  a  simple  string
   would be:

                   $TEXT(ROUTINE,<THIS IS A TEST STRING>)













                                    2-18
^L                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.17.1  Imbedded parameters and Qualifiers

   Variable text may be imbedded in strings formed  using  $TEXT.   These
   variables are indicated by using the action character, circumflex (^).
   The circumflex indicates that the next character is a qualifier  which
   specifies  the  type  of  parameter.  Most of the qualifiers act on an
   argument.  Immediately following the qualifier are "loc" and "pos"  of
   a  field  delimited  by  forward slashes.  The "loc" and "pos" are the
   same as  described  in  the  section  on  data-structure  manipulation
   instructions  with  the  addition  that  "loc" may also be an assembly
   literal (i.e.  [expression]).  The argument for the qualifier  is  the
   "word"  which would result from doing a LOAD pseudo-instruction on the
   specified  field.   Note  that  the  "loc"  field  may  reference  all
   accumulators  including S1, S2 and P in both the address field and the
   index register field.

   The legal qualifiers are:

   A       Suppress the free CRLF at end of line *
   B       The 'field' is the address of an object block ***
   C       The argument is a universal date/time which is
              printed as 'hh:mm:ss'  **
   D       The argument is a signed decimal number
   E       The argument is a GALAXY error code
              (-1 for last error)
   F       The 'field' is the address of a file-descriptor (FD) ***
   H       The argument is a universal date/time which is
              printed as 'dd-mmm-yy hh:mm:ss'  **
   I       INDIRECT text.  The 'field' contains address of an ITEXT
              macro.  See description of ITEXT below. ***
   J       Type a linefeed
   K       Type a vertical tab
   L       Type a formfeed
   M       Type a carriage-return
   N       The argument is a network NODE name or number
   O       The argument is an unsigned octal number
   P       The argument is a user ID. (PPN or user name) **
   Q       The argument is a byte pointer to an ASCIZ string ***
   T       The field is the address of an ASCIZ string
   U       The argument is a directory (PPN or directory name) **
   V       The argument is a version number in standard format
   W       The argument is six SIXBIT characters, trailing blanks
              suppressed
   0       Replace the free CRLF at end of line with a NULL *
   1       The argument is an OBJECT-TYPE
   5       The argument is 5 ASCII characters, left justified
   6       The low-order 6 bits of the argument represent a SIXBIT
              character
   7       The low-order 7 bits of the argument represent an ASCII
              character
   ^      Type a circumflex (i.e. ^^ produces ^).



                                    2-19
^L   MACROS AND PSEUDO-INSTRUCTIONS


   * These qualifiers may appear anywhere in the $TEXT call

   ** If the argument to these is '-1', the current value of the
   parameter is used.

   *** Note that for the ^B and ^F qualifiers it is the 'field' rather
   than the the 'argument' (i.e.  the contents of the field) that is
   used.


   Some examples of the use of qualifiers are:

      ^D/@-1(P)/     ^O/CONTNT/     ^E/[ERFNF$]/     ^D/COPIES,777/

   Some examples of $TEXT are:

      $TEXT(TTYOUT,<This is line ^D/LINENO/ of page ^D/PAGENO/>)

      $TEXT(,<?Error number ^O/T1/ - ^T/@MSGTAB(T1)/>)

      $TEXT(<-1,,BLOCK>,<Store this message in location BLOCK>)

































                                    2-20
^L                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.17.2  Field Justification

   The output generated by each $TEXT qualifier may  be  justified  in  a
   fixed  length  field  and padded appropriately.  Each qualifier may be
   augmented by 3 additional arguments:

                              ^Dabc/LOCATION/

   The three arguments a, b, and c specify the field-width, justification
   and padding character as follows:

         o  Field-width - is the width of the field in which to place the
            output.   There  is  no  default  for  this  field  so  if  a
            fixed-length  field  is  desired,  this  argument   must   be
            specified.

         o  Justification Specifier - This field is  a  single  character
            which  must  be  one of R, L, or C for right, left, or center
            respectively.   This  field  specifies  "justification"   not
            "padding".   So,  R  means  Right Justified (or Left padded).
            The default for this field is L for all qualifiers  except  O
            and D which default to R.

         o  Padding Character - This is any single character (except  for
            "/")  which  is  used to pad the field to its desired length.
            The default is a space in all cases.


   For example:

             $TEXT(,<^O6R0/[3]/ produces 000003>)

             $TEXT(,< To get just the date use ^H9/[-1]/>)



   2.17.3  ITEXT

   Just as ^T can be used to include remote  ASCIZ  strings  in  a  $TEXT
   call,  the  ^I qualifier can be used to include strings which are more
   complex (i.e.  have imbedded parameters).  The argument to  an  ^I  is
   the address of a block which is built by an ITEXT macro.  For example:

            $TEXT(routine,<Error code ^O/T1/ - ^I/@MSGTAB(T1)/>)


   MSGTAB:  [ITEXT(No privs at PC ^O/FOO/>)]

   [ITEXT(Illegal function ^D/FCNBLK/>)]

   Any qualifier can be used in an ITEXT including ^I,  so  they  may  be
   nested.


                                    2-21
^L   MACROS AND PSEUDO-INSTRUCTIONS


   2.17.4  Text Output Routine

   The Text Output Routine (TOR) is the subroutine specified as the first
   argument in a $TEXT call or as the default subroutine used by $TEXT as
   specified in the program's Initialization Block.

   This routine is called by the $TEXT processor with each  character  of
   the  decoded  ASCII string.  The character is passed to the routine as
   the low-order 7 bits of accumulator S1.

   The Text Output Routine may use accumulators S1 and S2.   Accumulators
   T1  through  T4,  P1  through  P4,  and  P  may not be used in the TOR
   (without being saved) nor are their contents in any way meaningful  to
   the  routine  (except  P  which  is  the  pushdown list pointer).  The
   contents of accumulators 13, 14, 15, and 16 are guaranteed to  be  the
   same  as they were upon execution of the $TEXT unless they are changed
   by the Text Output Routine  in  which  case  their  contents  will  be
   indeterminate for all subsequent calls to the TOR during the remainder
   of the $TEXT execution.

   The $TEXT Pseudo-instruction preserves 'all' accumulators,  hence  any
   changes made to any accumulators by the TOR (or by the $TEXT processor
   itself for that matter) will not be preserved (i.e.   the  instruction
   following  the  $TEXT will always see the same accumulator contents as
   did the $TEXT instruction.