Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

USING

Keyword Abbreviation Token (hex) Version(s) Classification
USING US{Shift+I} E6 4.x Preposition
LOCATE LO{Shift+C} E6 3.5, 7.0 Command and Statement
USING US{Shift+I} FB 3.5, 7.0 Preposition

  Syntax  
CMD fileNumber [ , USING format expression [ , expression ] ... ] [ { , | ; } ]
 ~ or ~
PRINT [ USING format expression [ , expression ] ... ] [ { , | ; } ]
 ~ or ~
PRINT# fileNumber [ , USING format expression [ , expression ] ... ] [ { , | ; } ]
 
 
Parameters Type Legal Value(s) Default Value Note(s)
fileNumber Integer  0 ~ 255    Must be an OPEN file#
expression any any    
format String  1 ~ 255 chars    Must include at least one # 
 
  Purpose  
Print an expression(s) with a specific format(s).

  Remarks  
The USING preposition makes a fundamental change to PRINT(#)/CMD: it makes a list of expression(s) required and forbids the use of SPC and TAB.  It allows a custom format for each expression.  This is the BASIC equivalant of C's "printf" family of functions (altough it is less versitilie).
 
The USING preposition is pretty versatile; it will accept any number or type of expressions that conform to the format.  The format consists of one or more fields.  The main requirement (well, recommendation) is the type of each expression corresponds with the type of field in the format string.  Each field is specified with one or more special characters:
 
Field Char(s) Expression Type Position in Field Number of uses
in Field
Note(s)
# Numeric or String  Any 1 or more Reserve a character in the output field.
+ Numeric Any 0 or 1
(must 0 if - used)
Reserve a character for the sign; always print sign.
A zero expression will print with a + too.
(Normally, non-negatives do not print a sign.)
- Numeric  Any 0 or 1
(must 0 if + used)
Reserve a character for the sign.
Prints a - if expression is negative; otherwise a space.
(Normally, positive numbers can be 1 digit longer
than negatives numbers because no character is reserved.)
. Numeric  Any  0 or 1  Reserve a character for the decimal point; always print it.
(Normally, the expression prints as an integer with no decimal point) 
Numeric  Any but first or last*  0 or more  Reserve a character for seperating digits of a large number.
If the number is "big" the separator will appear between digits.
(Normally, all digits run together making big numbers hard too read.)
*If used in the first or last position of the field, it will always appear.
$ Numeric  First: fixed at beginning
Any other: floating
0 or 1*  Reserve a character for the monetary symbol.
If used as first character of field, it always appears there;
otherwise it will "float" -- it appears before the first digit.
Unforunately, you can't make it appear at the end of a field.
*If used more than once, the extras will operate like #.
^^^^ Numeric  End of field*  0 or 1  Reserve four characters for "scientific" format (like 1.5E+03).
Always print the number in "scientific" format.
(Normally "standard" format is used, resulting in *** if too big
or 0 if too small.)
*Attempts to use it at the beginning will literally output 4 carets;
attempts to use it inside a field will create two fields.
= String  Any  0 or 1*  Reserve a character for a string, and center the output field.
If the number of unused (padding) characters is odd,
the left side will have one more blank than the right side.
(Normally strings are left-aligned.)
*If used more than once, the extras will operate like #.
> String  Any 0 or 1*  Reserve a character for a string, and right-align the output field.
(Normally strings are left-aligned.)
*If used more than once, the extras will operate like #.
 
Except as noted above in the table (mainly the four carets), any character that is not a "Field Char" (listed in the table above) may be used to seperate fields in the format string.  There is no "escape mechanism" so there may be trouble using a "Field Char" as a literal character in the output.  This is true for any case of a literal #, or when you want a literal character immediately adjacent to a field; otherwise the not-a-Field-Char may be used normally (see examples). 
 
There are four possible "logical characters" that may be generated by the USING preposition (these are secret variables that can be set with PUDEF):
Name Default Char Description
blank   A "space" used to pad a field 
decimal point .
Used to separate integer and fraction parts of a number.
separator , Used to split a "big" number for easier reading. 
monetary symbol A "money" sign for displaying currency. 
 
If an expression results in more characters than reserved for a field in the format, then BASIC will do one of two things, depending on the type of expression.  For a string expression, the first (left-most) characters of the expression will be output (the string is right-truncated).  For a numeric expression, it will generate a * for all characters that would normally hold a digit.  If an expression uses fewer chacters than allocated by its field, the unused will be filled with blank(s).
 
For string expressions, the BASIC action of right-trunctation of "too many characters" seems fine for the default (left-aligned) field format.  It is questionable in regards to centered string expressions, and (in my opinion) is totally inappropriate for a right-aligned string.  Unlike the + and - Field Chars (which are mutually exclusive), a field may include both = and > characters (to center or right-align a string, respectively); in this case, the last such character in the field determines the output format.
 
For a numeric expression, the field is output (conceptually) as right-aligned.  This is opposite of normal PRINT(#)/CMD behavior.  Actually, numeric expressions are aligned with the decimal point, but this only appears in the output if it is included in the field of format.  Unfortunately, there is no way to left-align or center a numeric expression.  Possible work-arounds are to use PRINT(#)/CMD without USING to get left-aligned numbers, but then you can't control the format.  Also mixing BASIC statements which alternate between the inclusion and exclusion of USING can be a bit confusing (it also tends to make the program longer).  This only works for left-alignment or right-alignment.  Another work-around (also not very acceptable) is to output the number as string expression (i.e., use STR$ on the numeric expression to make it a string).  This method works for any string alignment: (default) left-alignment, center, or right-alignment.  Using a string field has the problem of loosing control of the numeric format; however you do not need to alternate between inclusion and exclusion of the USING preposition.  See examples.
 
Unfortunately, there is no direct way to force leading zeros on a numeric expression.  One kludge to accomplish this is to redefine the blank to be a zero (instead of the default space).  However this will require using PUDEF; often it requires multiple uses of PUDEF since you usually don't want all numbers to have leading zeros.  Further, this work-around fails when used in combination with a floating monetary symbol or seperator(s).
  
In the case of PRINT USING, output is sent to the (active) display screen; for CMD/PRINT# USING the output is sent to the device which corresponds with fileNumber (see OPEN) which may (but usually doesn't) refer to the display screen.  If the output does go the screen, many secret variables may be modified by printing control codes (see the PETSCII table).
 
If fileNumber was not previously OPEN'd, then a FILE NOT OPEN ERROR occurs.  If a field includes both + and - Field Chars or more than 1 decimal point then SYNTAX ERROR will be generated.  Failure to include at least one # in format (or completely omitting format) generates SYNTAX ERROR.  Failure to supply any expressions at all causes SYNTAX ERROR as well.  Attempts to include TAB or SPC prepositions/functions will also generate SYNTAX ERROR.
 
Unlike most BASIC commands and statments, no TYPE MISMATCH ERROR will occur if the expression does not match its corresponding field type in the format; in such cases, the type of expression "wins" the debate.  BASIC will use all Field Chars (regardless of format type) to output the expression; in such a case, all formatting is "lost", every field character will be interpretted as a generic # character.  This does not mean TYPE MISMATCH ERROR is impossible however; it may occur if an expression attempts to combine string and numeric values (without an appropriate conversion function). 
 
There are other issues with USING.  One issue is that although a "floating" monetary symbol is possible, a "floating" sign is not (unless you want the default "negative only" behavior).  A related issue is that the monetary symbol can only be fixed at the beginning of the field.  Another issue is that if a decimal point and trailing #(s) are not present, BASIC will round a numeric expression to generate an integer output (by itself, not suprising) -- However, when USING rounds a number (this could be round to integer or round to a fraction) it uses the "round to nearest" forumula, unlike BASIC's more typical "floor" method (see INT for the case of integers / no fraction).
 
If the format contains more fields than there are expressions, output will end (without error) at the the first field which is missing a corresponding expression; no part of the missing missing field will be output.  If there are more expressions than fields in the format, then the format is re-used from the beginning (with no spaces or carriage returns between each format that is output).  See examples.
 
The optional terminating semicolon (;) will cause the next output to "run together" with this statement's output.  In other words, no "new line" (see below) is sent to the output device.
 
The optional terminating comma (,) will (SCREEN DISPLAY ONLY) align the next output on a 10-column boundry (0-based).  It will also supress a "new line" (see below).  See PRINT for examples of the comma.  For non-screen devices, it functions the same as a terminating semicolon (because BASIC has no idea of the device's "output position").
 
If the statement does not end with one of the two optional punctuation marks (a comma or semicolon), then PRINT(#)/CMD will end by sending a "new line" to the output device.  By default, this is a terminating carriage return (code 13).  Under some cases (see OPEN) it may also send a terminating line feed (code 10).
 
Examples of not-a-Field-Char:
PRINT USING "# - # = #";5,2,3 :REM works because separated from #
5 - 2 = 3
 
READY.
PRINT USING "# -# = #";5,2,3  :REM fail
5  2 = 3
 
READY.
PRINT USING "# - # =#";5,2,3  :REM fail
5 - 2  3
 
READY.
 
Examples of too many or too few characters:
PRINT USING "VAL:###";1    :REM left padding for right-alignment (too few)
VAL:  1
 
READY.
PRINT USING "VAL:###";9999 :REM all * (too many digits)
VAL:***
 
READY.
PRINT USING "VAL:###"; "A"    :REM right padding for left-alignment (too few)
VAL:A
 
READY.
PRINT USING "VAL:###"; "ABCD" :REM right truncate for left-alignment (too many)
VAL:ABC
 
READY.
PRINT USING "VAL:>##"; "A"    :REM left padding for right-alignment (too few)
VAL:  A
 
READY.
PRINT USING "VAL:>##"; "ABCD" :REM right truncate for right-alignment (too many)
VAL:ABC
 
READY.
PRINT USING "VAL:=##"; "AB"   :REM left padding odd remainder for center (too few)
VAL: AB
 
READY.
PRINT USING "VAL:=##"; "ABCD" :REM right truncate for center (too many)
VAL:ABC
 
READY.
 
Examples of mutually exclusive field options:
PRINT USING "+##-"; 1     :REM error with numeric field

?SYNTAX ERROR 
READY.
PRINT USING ">##="; "AB"  :REM no error with string field (center is last)
 AB
 
READY.
PRINT USING "=##>"; "AB"  :REM no error with string field (right-align is last)
  AB
 
READY.
 
Examples of numeric alignment (with numeric-only Field Char present):
PRINT USING "###.##"; 1.7       :REM default right alignment (numeric)
  1.70
 
READY.
PRINT USING "###.##"; STR$(1.7) :REM default left alignment (string)
 1.7
 
READY.
PRINT USING ">##.##"; 1.7       :REM default right alignment (numeric)
  1.70
 
READY.
PRINT USING ">##.##"; STR$(1.7) :REM force right alignment (string)
   1.7
 
READY.
PRINT USING "=##.##"; 1.7       :REM default right alignment (numeric)
  1.70
 
READY.
PRINT USING "=##.##"; STR$(1.7) :REM force center alignment (string)
  1.7
 
READY.
 
Examples of numeric alignment (no numeric-only Field Char present):
PRINT USING "######"; 1.7       :REM default right alignment (numeric)
     2
 
READY.
PRINT USING "######"; STR$(1.7) :REM default left alignment (string)
 1.7
 
READY.
PRINT USING ">#####"; 1.7       :REM default right alignment (numeric)
     2
 
READY.
PRINT USING ">#####"; STR$(1.7) :REM force right alignment (string)
   1.7
 
READY.
PRINT USING "=#####"; 1.7       :REM default right alignment (numeric)
     2
 
READY.
PRINT USING "=#####"; STR$(1.7) :REM force center alignment (string)
  1.7
 
READY.
 
Examples of monetary symbol and separator:
PRINT USING "$##,###.##"; 1.7  :REM small number, left-fixed position $
$     1.70
 
READY.
PRINT USING "$##,###.##"; 1700 :REM big number, left-fixed position $
$ 1,700.00
 
READY.
PRINT USING "#$#,###.##"; 1.7  :REM small number, floating $
     $1.70
 
READY.
PRINT USING "#$#,###.##"; 1700 :REM big number, floating $ 
 $1,700.00
 
READY.
PRINT USING "###,###.#$"; 1.7  :REM floating $ (failure of right-fixed)
     $1.70
 
READY.
 
Examples of sign and more-expressions-than-fields (1 field, but 3 expressions):
PRINT USING "###:"; 1,0,-1  :REM floating sign (only for negatives)
  1:  0: -1:
 
READY.
PRINT USING "-##:"; 1,0,-1  :REM fixed left sign (only for negatives)
  1:  0:- 1:
 
READY.
PRINT USING "+##:"; 1,0,-1  :REM fixed left sign (all numbers)
+ 1:+ 0:- 1:
 
READY.
PRINT USING "##-:"; 1,0,-1  :REM fixed right sign (only for negatives)
 1 : 0 : 1-:
 
READY.
PRINT USING "##+:"; 1,0,-1  :REM fixed right sign (all numbers)
 1+: 0+: 1-:
 
READY.
 
 
Example of more-fields-than-expressions (3 fields, but 1 expression):
PRINT USING "SUM OF #.# PLUS #.# IS #.#"; 1
SUM OF 1.0 PLUS
 
READY.
 
 
Examples of "too small" number and "scientific" format:
PRINT USING "########"; 0.4   :REM 'standard' round to nearest (too small)
       0
 
READY.
PRINT USING "########"; 0.99  :REM 'standard' round to nearest
       1
 
READY.
PRINT USING "####^^^^"; 0.99  :REM 'psudo-scientific' (all integer / no fraction)
9900E-04
 
READY.
PRINT USING "#.##^^^^"; 0.99  :REM 'scientific' (one integer / various fraction)
9.90E-01
 
READY.
 
  Contrast With  
  See Also  

© H2Obsession, 2014
Comments