|
|
| Line 1: |
Line 1: |
| <span style="font-size:120%; color:black"><b><section begin=dpl_desc/>Print a UnicodeNamedArraylist<section end=dpl_desc/></b></span>
| | #REDIRECT [[Print (GenericNamedArraylist subroutine)]] |
| [[Category:UnicodeNamedArraylist methods|Print subroutine]]
| |
| <!--DPL?? Category:UnicodeNamedArraylist methods|Print subroutine: Print a UnicodeNamedArraylist-->
| |
| <p>
| |
| Print is a member of the [[UnicodeNamedArraylist class]].
| |
| </p>
| |
| | |
| This subroutine displays the contents of a UnicodeNamedArraylist on the user's
| |
| standard output device, typically a terminal.
| |
| The list item values, displayed in order by their subscript names,
| |
| are preceded by their item number and item name, both of which by default
| |
| are followed by a colon (<tt>:</tt>) and a blank.
| |
| ==Syntax==
| |
| %unamrayl:Print( [method] -
| |
| [, NumWidth=itemnumlen] -
| |
| [, Separator=separator] -
| |
| [, NameWidth=itemnamelen] -
| |
| [, Start=firstitem] -
| |
| [, MaxItems=maxitems] -
| |
| [, Label=label] )
| |
| ===Syntax Terms===
| |
| <dl>
| |
| <dt><i>%rc</i>
| |
| <dd>A numeric variable that is set to the number of UnicodeNamedArraylist items displayed.
| |
| <dt><i>%unamrayl</i>
| |
| <dd>A UnicodeNamedArraylist object.
| |
| <dt><i>method</i>
| |
| <dd>The method that is applied to ''%unamrayl'' items to produce the
| |
| printed output.
| |
| The method must take no parameters and produce an intrinsic (Float,
| |
| String, Fixed, Unicode) value.
| |
| It may be a system or user-written
| |
| method, a class Variable or Property, a local method ([[??]] refid=localm.),
| |
| or a [[Method variables|Method variable]].
| |
| | |
| The default value of ''method'' is <tt>ToString</tt>.
| |
| <dt><b>NumWidth=</b><i> itemnumlen</i>
| |
| <dd>The number of bytes in the display of each item to use for the
| |
| item number.
| |
| This is an optional parameter; if you specify a value, the parameter
| |
| name <tt>NumWidth</tt> is required.
| |
| | |
| Item numbers are right-justified within the indicated number of bytes, and they
| |
| are truncated on the left if the length of the item number exceeds the
| |
| space allocated for it.
| |
| The width must be a number between -1 and 10 inclusive.
| |
| If you specify a value of 0, the item number is not displayed.
| |
| | |
| If NumWidth is -1, the default, the method uses the minimum number
| |
| of bytes required to show the item number.
| |
| For example, one byte is required for item number 5, while five bytes
| |
| are required for item number 98764.
| |
| <dt><b>Separator=</b><i> separator</i>
| |
| <dd>A String, 15 characters or less, to be used to separate both the item
| |
| number and the item name from what follows.
| |
| That is, the ''separator'' you specify appears twice: once after the
| |
| item number and once after the item name.
| |
| | |
| This is an optional argument whose default is a colon (<tt>:</tt>).
| |
| A blank always follows the ''separator'' string.
| |
| If you specify a value, the parameter name <tt>Separator</tt> is required.
| |
| <dt><b>Start=</b><i> firstitem</i>
| |
| <dd>The item number of the initial item in the output display.
| |
| This is an optional argument, and it defaults to 1.
| |
| If you specify a value, the parameter name <tt>Start</tt> is required.
| |
| <dt><b>MaxItems=</b><i> maxitems</i>
| |
| <dd>The maximum number of items to display.
| |
| A zero or negative value means to display all the items.
| |
| | |
| This is an optional argument, and it defaults to zero.
| |
| If you specify a value, the parameter name <tt>MaxItems</tt> is required.
| |
| <dt><b>Label=</b><i> label</i>
| |
| <dd>A literal string that gets output before each line.
| |
| This is useful for “tagging” lines to make them more identifiable.
| |
| | |
| This is an optional argument whose default is a null string.
| |
| If you specify a value, the parameter name <tt>Label</tt> is required.
| |
| <dt><b>NameWidth=</b><i> itemnamelen</i>
| |
| <dd>The number of bytes in the display of the item name.
| |
| This must be a number from -1 through 255.
| |
| If you specify a value, the parameter name <tt>NameWidth</tt> is required.
| |
| | |
| Item names are left-justified within the indicated number of bytes, and they
| |
| are truncated on the right if the length of the item name exceeds the
| |
| space allocated for it.
| |
| This can result
| |
| in names being truncated in the middle of a character encoding of a Unicode
| |
| character that is not translatable to EBCDIC (as shown in
| |
| "[[Collections#Examples of subscript display format for named collections|Examples of subscript display format for named collections]]").
| |
| | |
| If you specify a value of 0, the item name is not displayed.
| |
| | |
| This is an optional argument; it defaults to -1, which directs the method to use
| |
| whatever number of bytes are necessary to show the entire item name.
| |
| For example, three bytes are required for item name <tt>Foo</tt>, while
| |
| eight bytes are required for item name <tt>Malmberg</tt>.
| |
| | |
| </dl>
| |
| ==Usage Notes==
| |
| <ul>
| |
| <li>All errors in Print result in request cancellation.
| |
| <li>Since the maximum number of bytes of a subscript name that can be
| |
| displayed is 255, and the names in UnicodeNamedArraylists can be 127 characters
| |
| long and might be character encoded on display, Print may not
| |
| be able to display the full name of certain item subscripts.
| |
| | |
| If all the characters in a Unicode name need to be encoded, the 255-byte limit
| |
| can still accommodate 31 characters.
| |
| <li>[[Audit (UnicodeNamedArraylist subroutine)|Audit]] and [[Trace (UnicodeNamedArraylist subroutine)|Trace]] are
| |
| the same as Print except they send their output to the audit trail
| |
| and selected trace destination, respectively.
| |
| <li>For examples of Print method calls, see [[Collections#Printing a collection|Printing a collection]].
| |
| </ul>
| |