home *** CD-ROM | disk | FTP | other *** search
/ ftp.robelle3000.ai 2017 / ftp.robelle3000.ai.tar / ftp.robelle3000.ai / changes / supr4p61ux.txt < prev    next >
Text File  |  2003-05-06  |  35KB  |  955 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.                             SUPRTOOL Version 4.6.01
  7.  
  8.  
  9.                           Database Handyman for HP-UX
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                  Change Notice
  17.                            Installation Instructions
  18.                           Addendum to 4.3 User Manual
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                             Suprtool         4.6.01
  26.                             Suprlink         4.6.01
  27.                             STExport         4.6.01
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.                          Robelle Solutions Technology
  39.                           Suite 201, 15399-102A Ave.
  40.                          Surrey, B.C.  Canada V3R 7K1
  41.  
  42.  
  43.  
  44.                              Phone:  604.582.1700
  45.                               Fax:  604.582.1799
  46.  
  47.                          E-mail:  support@robelle.com
  48.                              Web:  www.robelle.com
  49.  
  50.                                   March 2002
  51.           Program  and  Manual  Copyright  Robelle Solutions Technology Inc.
  52.           1981-2002
  53.  
  54.  
  55.           Permission is granted  to  reprint  this  document  (but  not  for
  56.           profit), provided that copyright notice is given.
  57.  
  58.  
  59.  
  60.  
  61.           QEDIT  and SUPRTOOL are trademarks of Robelle Solutions Technology
  62.           Inc.  Other product and company names mentioned herein may be  the
  63.           trademarks of their respective owners.
  64.  
  65.  
  66.  
  67.    Introducing Suprtool/UX Version 4.6
  68.  
  69.  
  70.                *  Highlights
  71.                *  Known Problems
  72.                *  Compatibility
  73.                *  CPU Serial Number (uname)
  74.                *  Documentation
  75.                *  Documentation Format
  76.  
  77.           Use  Suprtool/UX  to  read,  select, and sort data from Oracle and
  78.           Allbase databases and from data files with  fixed-length  records.
  79.           Suprtool/UX  is  designed  to be similar to Suprtool for MPE while
  80.           providing  necessary   HP-UX   features.    Suprlink/UX   provides
  81.           high-speed data-file linking based on a sort key.  Use STExport to
  82.           convert fields in a self-describing input file into an output file
  83.           that can be imported into different applications.
  84.   
  85.    Highlights in Version 4.6.01
  86.  
  87.  
  88.           *  Suprtool would incorrectly coerce large negative numbers from a
  89.              Packed field to another Packed or Display field.
  90.  
  91.           *  Suprtool would fail with prefetch point failure if the file had
  92.              an uneven record size and an uneven blocking facter.
  93.  
  94.           *  STExport  now  properly converts the Roman 8 universal monetary
  95.              symbol to the Euro-Symbol in the HTML and XML commands.
  96.  
  97.           *  The Item command would fail if a definition or Item command was
  98.              already  issued  for  a  field,  if  the  input  source  was  a
  99.              self-describing file and  and extract range  was  used  or  all
  100.              items from a dataset were extracted.
  101.  
  102.           *  The  XML command would fail to conve SMB>" to ">" and "<" to
  103.              "<".
  104.  
  105.           *  The XML and HTML commands failed to convert "&" to "&".
  106.  
  107.  
  108.    Highlights in Version 4.6
  109.  
  110.  
  111.           *  Support for HP Eloquence databases has been added.
  112.  
  113.           *  Suprtool  incorrectly  rounded  Real  and  Long  target data in
  114.              arithmetic expres
  115.  
  116.  
  117.    Highlights in Version 4.5
  118.  
  119.  
  120.           *  Support for "well-formed" XML in STExport.
  121.  
  122.           *  Suprtool, STExport and Suprlink can now  have  warnings  turned
  123.              off when run from batch with the set warnings off command.
  124.  
  125.           *  Some division operations would not work properly if the decimal
  126.              portion was large and the target type was packed or zoned.
  127.  
  128.  
  129.    Highlights in Version 4.4
  130.  
  131.  
  132.           *  Suprtool now supports string expressions in  both  the  Extract
  133.              and  If commands.  String expressions allow users to select and
  134.              format  their  byte-type  data  in  numerous  new  ways.   This
  135.              includes  combining  byte-type  fields together, upshifting and
  136.              downshifting data, and trimming  blanks.   These  new  features
  137.              combine  to  reduce  the  number  of tasks needed to select and
  138.              format the data the way you need it.
  139.  
  140.           *  Suprtool now supports 5,100 bytes of constants to be extracted.
  141.              (only NM and HP-UX)
  142.  
  143.           *  Suprtool,  Suprlink and STExport now have the ability to create
  144.              their own persistent redo stacks.  The contents of these stacks
  145.              can  be recalled not only in the current session, but also in a
  146.              future session.
  147.  
  148.  
  149.    Known Problems
  150.  
  151.           There are no known problems at this time.
  152.  
  153.  
  154.    Compatibility
  155.  
  156.           Suprtool/UX is compatible with HP-UX 9.0, all  versions  of  HP-UX
  157.           10.x, as well as Oracle version 7.1.3.2.0.
  158.  
  159.           On  HP-UX  10.x,  Suprtool/UX  creates  all  of  its temporary and
  160.           scratch  files  in  /var/tmp,  unless  you  have  overridden   the
  161.           temporary directory with the TMPDIR environment variable.
  162.  
  163.           Suprtool  for  HP-UX  typically  comes  with  two  versions in two
  164.           different directories on your tape.  The version  of  Suprtool  in
  165.           /opt/robelle  is  compatible  with  HP-UX  10.20  and  later.  The
  166.           version of Suprtool in /usr/robelle is  compatible  with  versions
  167.           earlier than HP-UX 10.20.
  168.  
  169.  
  170.  
  171.    CPU Serial Number (uname)
  172.  
  173.           This  program  runs  only  on  CPUs whose serial numbers have been
  174.           encoded (the "uname" on HP-UX).  If it fails to run and you get an
  175.           "invalid HPSUSAN" error message, call Robelle for assistance.
  176.  
  177.  
  178.    Documentation
  179.  
  180.           You  can  access these files from within Suprtool by simply typing
  181.           the Help command.
  182.  
  183.           If you are already familiar with Suprtool, you can access only the
  184.           Suprtool/UX  topics that are different from those of Suprtool/MPE.
  185.           The "Running" section of  the  Help  file  has  been  updated  for
  186.           Suprtool/UX.  You can access it with the following Help command:
  187.  
  188.                >help running
  189.  
  190.  
  191.    Documentation Formats
  192.  
  193.           The user manuals for Suprtool and its components are all available
  194.           in the several popular formats such as PDF and HTMLHelp at:
  195.  
  196.              http://www.robelle.com/library/manuals/
  197.  
  198.  
  199.    Installation of 4.6.01
  200.  
  201.  
  202.           The following instructions describe the installation process of  a
  203.           new  Suprtool  release.   The  new  version overwrites an existing
  204.           version of Suprtool on your HP-UX system.
  205.  
  206.  
  207.    Who Should Use These Instructions?
  208.  
  209.           The system  manager  should  use  the  following  instructions  to
  210.           install  Suprtool/UX.   During the installation, which should take
  211.           only a few minutes, no one can use Suprtool/UX.
  212.  
  213.  
  214.  
  215.    Summary of Installation Steps
  216.  
  217.           To install Suprtool, follow these steps:
  218.  
  219.           1. Log in as root.
  220.  
  221.           2. Create the correct directory structure.
  222.  
  223.           3. Restore  Suprtool/UX  and  its  associated   files   from   the
  224.              distribution tape.
  225.  
  226.           4. Set  up  variables  to  let  Suprtool know where its supporting
  227.              files are located.
  228.  
  229.  
  230.    Installation Assistance
  231.  
  232.           If you have any questions or run into any  problems,  please  call
  233.           us.   Technical  support is available on weekdays from 7 a.m. to 4
  234.           p.m. Pacific time at 1.604.582.1700.  Technical support  can  also
  235.           be obtained via e-mail at:  support@robelle.com
  236.  
  237.  
  238.    Step 1:  Log In as Root
  239.  
  240.           There are two ways you can log in as root:
  241.  
  242.           a. Exit from HP-UX and log in with root as the user name.
  243.  
  244.           b. If you are already logged in, you can execute this command:
  245.  
  246.                   su -
  247.  
  248.           In  either case, you have to know and supply the user password for
  249.           root.
  250.  
  251.  
  252.    Step 2:  Create Robelle Directory
  253.  
  254.           Before restoring files, you must first create the directory  where
  255.           Suprtool/UX will reside:
  256.  
  257.                mkdir /opt/robelle
  258.  
  259.  
  260.    Step 3:  Restore Files
  261.  
  262.           Use  the  following  command to restore the Suprtool/UX files from
  263.           the distribution tape:
  264.  
  265.                tar xv /opt/robelle
  266.  
  267.           This command assumes your tape device is /dev/rmt/0m.   If  it  is
  268.           not,  you need to specify your tape device using the "f" option in
  269.           the tar command.  For example, if your tape device is /dev/rmt/1m,
  270.           you need to use the following command to restore the files:
  271.  
  272.                tar xvf /dev/rmt/1m /opt/robelle
  273.  
  274.  
  275.    Step 4:  Set the ROBELLE Variable
  276.  
  277.           You must set the ROBELLE environment variable so that Suprtool can
  278.           find its Help and Suprmgr files.
  279.  
  280.  
  281.    Bourne and Korn Shells
  282.  
  283.                export ROBELLE=/opt/robelle
  284.  
  285.  
  286.    C Shell
  287.  
  288.                setenv ROBELLE /opt/robelle
  289.  
  290.  
  291.  
  292.    Enhancements in Version 4.6.01
  293.  
  294.  
  295.           We  constantly  provide  Suprtool  users  with  new features.  The
  296.           following section describes the new enhancements to Suprtool since
  297.           the last major release.
  298.  
  299.  
  300.    Enhancements in 4.6.01
  301.  
  302.           There  are  no  Enhancements  to the version of Suprtool, just bug
  303.           fixes.
  304.  
  305.  
  306.    Bugs Fixed in Version 4.6.01
  307.  
  308.  
  309.    Packed and Display Coercion.   Suprtool would  incorrectly  coerce  large
  310.           negative numbers from one Packed or Display field.
  311.  
  312.  
  313.    Input Filename  (start/end).    Suprtool  would  fail with prefetch point
  314.           failure if the file had  an  uneven  record  size  and  an  uneven
  315.           blocking factor.
  316.  
  317.  
  318.    HTML and  XML  commands.    STExport  now  properly  converts the Roman 8
  319.           universal monetary symbol to the Euro-Symbol in the HTML  and  XML
  320.           commands.
  321.  
  322.           The XML command would fail to convert ">" to "gt" and "<" to "lt".
  323.  
  324.           The XML and HTML commands failed to convert "" to "amp".
  325.  
  326.  
  327.    Enhancements in Version 4.6
  328.  
  329.           Every year we provide Suprtool/UX users with  new  features.   The
  330.           following section describes the new enhancements to Suprtool since
  331.           the last major release.
  332.  
  333.  
  334.    Support for HP Eloquence
  335.  
  336.           Suprtool for HP-UX now supports HP Eloquence.   The  only  version
  337.           that Suprtool 4.6 has been tested with is A.06.31.
  338.  
  339.           HP  Eloquence is a database that runs on HP-UX, which has an Image
  340.           like intrinsic layer.   For  more  information  on  this  database
  341.           please visit their web site at:
  342.  
  343.            http://www.hp-eloquence.com/
  344.  
  345.           We  are  interested  in  people wanting to have their old familiar
  346.           Suprtool for MPE commands, such as Base, Get, Update,  Delete  and
  347.           Put.
  348.  
  349.           The  syntax  for the commands in the HP-UX version is identical to
  350.           those commands on MPE.
  351.  
  352.  
  353.  
  354.  
  355.    Bugs Fixed in Version 4.6
  356.  
  357.  
  358.    Real and Long Arithmetics.   Suprtool incorrectly rounded Real  and  Long
  359.           target data in arithmetic expressions
  360.  
  361.  
  362.  
  363.    Enhancements in Version 4.5
  364.  
  365.           Every  year  we  provide Suprtool/UX users with new features.  The
  366.           following section describes the new enhancements to Suprtool since
  367.           the last major release.
  368.  
  369.  
  370.    Set Warnings Off
  371.  
  372.           Suprtool,  STExport  and  Suprlink  have  a new command called Set
  373.           Warnings which when  turned  off  will  no  longer  print  warning
  374.           messages if you are running in batch.
  375.  
  376.           In  Suprtool,  you  can  simulate  batch mode with the command Set
  377.           Interactive off.  If Set Warnings is off, Suprtool will honour the
  378.           value of the Interactive setting, provided Set Warnings off is set
  379.           after the Set Interactive command.
  380.  
  381.  
  382.    XML Command
  383.  
  384.           STExport will now generate "well-formed" XML output  with  just  a
  385.           few commands.
  386.  
  387.            /opt/robelle/bin/stexport
  388.            $input file1sd
  389.            $xml
  390.            $output myxml
  391.            $xeq
  392.  
  393.           These  four  simple commands will generate the following file that
  394.           packages such as XMLSpy will consider  to  be  "well-formed"  XML.
  395.           The result of such an STExport task will look as follows:
  396.  
  397.            <?xml version='1.0'?>
  398.            <file>
  399.            <record>
  400.            <CITY>Los Altos</CITY>
  401.            <CREDIT-RATING>100000</CREDIT-RATING>
  402.            <CUST-ACCOUNT>4003302</CUST-ACCOUNT>
  403.            <CUST-STATUS>20</CUST-STATUS>
  404.            <NAME-FIRST>Ralph</NAME-FIRST>
  405.            <NAME-LAST>Perkins</NAME-LAST>
  406.            <STATE-CODE>CA</STATE-CODE>
  407.            <STREET-ADDRESS>Room 655</STREET-ADDRESS>
  408.            <STREET-ADDRESS>Los Altos     040033022</STREET-ADDRESS>
  409.            <ZIP-CODE>93002</ZIP-CODE>
  410.            </record>
  411.  
  412.            </file>
  413.  
  414.  
  415.           By  default  STExport  will  add  the  simplest version tag at the
  416.           beginning of the file, then  it  inserts  a  <file>  and  matching
  417.           </file>  at  the beginning and the end of the file.  Then STExport
  418.           encloses each record  from  the  input  file  in  a  <record>  and
  419.           </record> tag.  Finally, the Self-Describing tags are added around
  420.           each field's data values and edited appropriately.
  421.  
  422.           Naturally users would want options to customize  and  specify  the
  423.           various  options  and tags themselves, in order to generate a file
  424.           that is acceptable to their tools.
  425.  
  426.           You can specify the "version" tag at the beginning of the XML file
  427.           with the following command:
  428.  
  429.            xml version "?xml version='1.0' encoding='ISO-8859-1'?"
  430.  
  431.           STExport  will put the "<" and ">" around what is specified in the
  432.           version string.  In addition, you can  customize  the  "file"  and
  433.           "record" tags with the following simple commands:
  434.  
  435.            xml file "orders" record "orderdetail"
  436.  
  437.           You  can  enter  multiple  XML  commands  per  task to set the XML
  438.           options you require.
  439.  
  440.            $in file1sd
  441.            $xml version "?xml version='1.0' encoding='ISO-8859-1'?"
  442.            $xml file "Orders" record "Details"
  443.            $out myfile
  444.  
  445.           An example of the output generated by the  above  commands  is  as
  446.           follows:
  447.  
  448.             <?xml version='1.0' encoding='ISO-8859-1'?>
  449.             <Orders>
  450.             <Details>
  451.             <CITY>Los Altos</CITY>
  452.             <CREDIT-RATING>100000</CREDIT-RATING>
  453.             <CUST-ACCOUNT>4003302</CUST-ACCOUNT>
  454.             <CUST-STATUS>20</CUST-STATUS>
  455.             <NAME-FIRST>Ralph</NAME-FIRST>
  456.             <NAME-LAST>Perkins</NAME-LAST>
  457.             <STATE-CODE>CA</STATE-CODE>
  458.             <STREET-ADDRESS>Room 655</STREET-ADDRESS>
  459.             <STREET-ADDRESS>Los Altos    040033022</STREET-ADDRESS>
  460.             <ZIP-CODE>93002</ZIP-CODE>
  461.             </Details>
  462.             </Orders>
  463.  
  464.           In  XML the tags that surrounded the data can not have any special
  465.           characters other than  hyphen,  underscore  and  period  ("-","_",
  466.           ".").   So STExport replaces any of the invalid special characters
  467.           with a "." by default.  You can change the default character to be
  468.           something else with the following set command:
  469.  
  470.             $Set xmltagchar "_"
  471.  
  472.           STExport  will  only allow the hyphen, underscore and period to be
  473.           set with this command.
  474.  
  475.           A Document Type Declaration can be made at the  beginning  of  the
  476.           file   via  the  !DOCTYPE  specification.   This  typically  tells
  477.           whatever tool that is parsing the xml file where the DTD  for  the
  478.           file resides.
  479.  
  480.           In STExport you can specify simple one-line doctype specs with the
  481.           following command:
  482.  
  483.            xml doctype '!DOCTYPE address-book SYSTEM "address-book.dtd"'
  484.  
  485.           This will write the doctype specification at the top of the output
  486.           file, directly after the XML version specification.
  487.  
  488.  
  489.           All  of STExport's XML command options (version, doctype, file and
  490.           record) allow for a string to be passed  via  surrounding  quotes.
  491.           The  quotes  may be either single or double, but keep in mind that
  492.           if the string  is  to  contain  double  quotes,  then  you  should
  493.           surround the entire string with single quotes.
  494.  
  495.  
  496.           So  to summarize this new feature the following commands have been
  497.           added for XML support.  The XML command has the following options:
  498.  
  499.                XML
  500.                          VERSION "string"
  501.                          DOCTYPE "string"
  502.                          FILE    "string"
  503.                          RECORD  "string"
  504.  
  505.           The  following set command has been added to aid in the conversion
  506.           of special characters in the tag:
  507.  
  508.             set xmltagchar "."
  509.  
  510.  
  511.  
  512.  
  513.    Bugs Fixed in Version 4.6
  514.  
  515.  
  516.    Dividing Zero by Zero.   Some division operations would result in a large
  517.           number  when  dividing  zero by zero if the target type was zoned,
  518.           packed or quad integer.  [4.1.11]
  519.  
  520.  
  521.    Divide Operations.   Suprtool could not properly convert the result of  a
  522.           division  operation  if  the  target  was  zoned or packed, in one
  523.           specific case.  [4.1.11]
  524.  
  525.  
  526.    Extract Character Constant.    If  you  had  a  extract  of  a  character
  527.           constant,  and if the constant specified was not completely filled
  528.           in for all of the positions in the length of the  field,  Suprtool
  529.           would would produce strange results.  [4.1.11]
  530.  
  531.  
  532.  
  533.    Define Command.    A  warning  message  has  been added in the case where
  534.           fields defined  as  non-standard  integers,  will  be  treated  as
  535.           strings.  [4.4.11]
  536.  
  537.  
  538.    Extract Command.    The  error  message  that  prints when the expression
  539.           specified cannot be coerced/converted into  the  target  has  been
  540.           improved.  [4.4.11]
  541.  
  542.  
  543.    If $Read  Operations.    Suprtool  would incorrectly put commands entered
  544.           thru the $read facility into the redo file or stack when  executed
  545.           thru a Use file.  [4.4.13]
  546.  
  547.  
  548.    Table Command.   Suprtool would not hold on to a table in some cases when
  549.           the hold option was specified in the table command.   The  CM  and
  550.           HP-UX  versions of Surptool would not hold on to the correct table
  551.           in some cases.  [4.4.13]
  552.  
  553.  
  554.    Verify Command.   Verify Define will now  show  the  correct  information
  555.           when defining non-standard integers.  [4.4.11]
  556.  
  557.  
  558.    Enhancements in Version 4.4
  559.  
  560.           Every  year  we  provide Suprtool/UX users with new features.  The
  561.           following section describes the new enhancements to Suprtool since
  562.           the last major release.
  563.  
  564.  
  565.  
  566.    Extracting Constants
  567.  
  568.           Previously  Suprtool  was  limited to 1,530 bytes of constants for
  569.           MPE/iX and HP-UX versions of Suprtool.  This limit  has  now  been
  570.           increased  to 5,100 bytes.  The MPE/V version of Suprtool is still
  571.           limited to 1,275 bytes.
  572.  
  573.  
  574.    Persistent Redo
  575.  
  576.           Commands entered at the Suprtool prompt  are  saved  in  something
  577.           called the redo stack.  You can recall commands from this stack by
  578.           using other commands such as Before, Do and Redo.  By default, the
  579.           redo  stack is stored in a temporary file and discarded as soon as
  580.           you exit Suprtool.  This temporary stack is not  preserved  across
  581.           Suprtool invocations.
  582.  
  583.           The  new  Set  Redo  command  assigns a permanent file as the redo
  584.           stack, allowing the stack to become available for future  Suprtool
  585.           invocations.   For  example,  to  assign  the  myredo  file  to  a
  586.           persistent redo stack, enter
  587.  
  588.                >set redo myredo
  589.  
  590.           If the file does  not  exist,  Suprtool  creates  it.   Otherwise,
  591.           Suprtool  uses  the  existing  file.   All subsequent commands are
  592.           written to the persistent redo stack.  This setting is  valid  for
  593.           the  duration  of  the  Suprtool  session.   As  soon  as you exit
  594.           Suprtool, the setting is discarded.  Next time you  run  Suprtool,
  595.           you will get the temporary stack.
  596.  
  597.           If  the  file  name is not qualified, the redo stack is created in
  598.           the current working directory.  This may be desirable if you  want
  599.           to  have  separate  stacks.   If  you  want to always use the same
  600.           persistent stacks, you should qualify the name.
  601.  
  602.           The Verify command shows which stack is currently in use.   If  it
  603.           shows  <temporary>,  it means Suprtool is using the default stack.
  604.           Anything else is the name  of  the  file  used  on  the  Set  Redo
  605.           command.
  606.  
  607.  
  608.    Concurrency
  609.  
  610.           When  Suprtool  uses the default temporary stack, it is accessible
  611.           only to that particular instance of Suprtool.  You can run as many
  612.           Suprtool  instances  as  you  need  and each one gets its own redo
  613.           stack.  With temporary stacks, you  will  never  have  concurrency
  614.           problems.
  615.  
  616.           If  you  start  using  a persistent redo stack, however, you might
  617.           start running into concurrency problems.  A persistent redo  stack
  618.           can  be  used by only one Suprtool instance at a time.  If you try
  619.           to use a persistent redo stack that is already in  use,  you  will
  620.           get the following message:
  621.  
  622.                >set redo myredo
  623.                The redo file is already in use.
  624.                Unable to open file for REDO stack
  625.  
  626.           In this situation, Suprtool continues to use the redo stack active
  627.           at the time and lets you continue working as normal.
  628.  
  629.           Qedit can also have permanent redo stacks.   To  prevent  products
  630.           from  writing  to  each other's redo stack, it is advisable to use
  631.           separate stacks for each product by  giving  them  different  file
  632.           names.  For example if you use
  633.  
  634.                >set redo myredo
  635.  
  636.           you  will  have  a  redo  stack  called  myredo  for your Suprtool
  637.           commands.  If you exit Suprtool, then run  Qedit  and  supply  the
  638.           same  Set Redo command, your Qedit commands will be written to the
  639.           same file that was used for your Suprtool commands.
  640.  
  641.  
  642.    String Expressions
  643.  
  644.           Both the Extract and If  commands  have  been  enhanced  to  allow
  645.           string expressions, which can be used to:
  646.  
  647.  
  648.           1. Combine two fields together (using the + operator).
  649.  
  650.           2. Remove spaces (using the built-in trim functions).
  651.  
  652.           3. Upshift or downshift characters.
  653.  
  654.           String  expressions  reduce  the number of tasks required for many
  655.           common operations involving byte-type fields.  Fewer  tasks  means
  656.           that  Suprtool delivers data to your applications faster than ever
  657.           before.
  658.  
  659.           These  changes  are  so  extensive  that  string  expressions  are
  660.           described  separately  for  the  Extract and If Commands.  See the
  661.           sections  below  for  specific  details  and  examples  of  string
  662.           expressions.
  663.  
  664.  
  665.    Extract Command
  666.  
  667.           You can now use string expressions in the Extract command.  String
  668.           expressions allow you to combine byte-type fields together  (using
  669.           the  +  operator)  or  operate  on  byte-type  fields with special
  670.           functions.  In many cases, you can now reduce the number of  tasks
  671.           required  to  format the data the way you want.  Fewer tasks means
  672.           that Suprtool delivers the data where you need it faster than ever
  673.           before.  To extract a string expression, use this syntax:
  674.  
  675.                     EXTRACT target-field = expression
  676.  
  677.  
  678.    Target-Field
  679.  
  680.           The  target-field  determines  the byte-length for the expression.
  681.           The data-type must be Byte or Char.  The expression  is  extracted
  682.           during  the  output  phase  and  cannot  be used by other Suprtool
  683.           commands that accept fields (e.g., Sort).
  684.  
  685.  
  686.    Examples
  687.  
  688.                >extract id-no = warehouse-no + bin-no
  689.  
  690.                >extract full-name = first-name + last-name
  691.  
  692.  
  693.    Constants vs. Expressions
  694.  
  695.           If you have an  string  expression  that  starts  with  a  string,
  696.           Suprtool  assumes  that  you  are  attempting  to extract a single
  697.           string value and not a string expression.   To  specify  a  string
  698.           expression  that  starts  with a constant, surround the expression
  699.           with parentheses.  For example,
  700.  
  701.                Incorrect
  702.                >extract name = " " + product-desc
  703.  
  704.                Error:  Missing comma or invalid arithmetic expression
  705.  
  706.                Correct
  707.                >extract name = (" " + product-desc)
  708.  
  709.  
  710.    Variable Length Strings
  711.  
  712.           String expressions use variable-length  strings.   Suprtool  keeps
  713.           track  of  the length of every string, and all operations are done
  714.           using the actual string length.  For fields,  the  length  of  the
  715.           string  is  the length of the field.  If you do not want to retain
  716.           all of the spaces in a field, use one  of  the  built-in  trimming
  717.           functions.
  718.  
  719.           String  constants  are  created  with  the  exact  length  of  the
  720.           constant.  For example, the string "abc" is three characters  long
  721.           and the string "a" is one.
  722.  
  723.           When assigning the string expression to the target field, Suprtool
  724.           pads the final string value with spaces to  fill  out  the  target
  725.           field.   String  expressions longer than the target field generate
  726.           an error.
  727.  
  728.                >in testfile
  729.                >def a,1,10,byte
  730.                >ext a="I'm too long for this container"
  731.  
  732.                Error:  String is too long for the specified item
  733.  
  734.  
  735.    String Truncation
  736.  
  737.           Suprtool produces an error if the string expression is longer than
  738.           the  target field.  You cannot override this error with Set Ignore
  739.           On.  To help avoid the error, you may want to trim trailing spaces
  740.           from  the expression before assigning it to the target field.  For
  741.           example,
  742.  
  743.                >extract new-field = $trim(a + b + c)
  744.  
  745.  
  746.    Upshifting Strings ($Upper)
  747.  
  748.           Use the built-in function $upper to upshift all of the  characters
  749.           of  a  string expression into uppercase characters.  This function
  750.           can be used to  upshift  a  single  field,  a  complicated  string
  751.           expression,  or  any  subpart  of  an  expression.  Both ASCII and
  752.           Roman-8 characters are upshifted by $upper.  For example,
  753.  
  754.                >extract city-up = $upper(city)
  755.  
  756.                >extract full-name = $upper(first + last)
  757.  
  758.                >extract desc = desc-1 + $upper(desc-2)
  759.  
  760.  
  761.    Downshifting Strings ($Lower)
  762.  
  763.           If you want to downshift all characters of a string expression  to
  764.           lowercase, use the built-in function $lower.  This function can be
  765.           used to downshift a single field, a complicated string expression,
  766.           or   any  subpart  of  an  expression.   Both  ASCII  and  Roman-8
  767.           characters are downshifted by $lower.  For example,
  768.  
  769.                >extract city-lower-case = $lower(city)
  770.  
  771.                >extract city-state = $lower(city + state)
  772.  
  773.                >extract desc = desc-1 + $lower(desc-2)
  774.  
  775.  
  776.    Trimming Spaces ($Trim, $Ltrim, $Rtrim)
  777.  
  778.           Use one of three built-in string functions to  remove  leading  or
  779.           trailing  spaces  from  a  string expression.  The three functions
  780.           are:
  781.  
  782.  
  783.           $Trim:      Remove leading and trailing  spaces  from  the  string
  784.                       expression.
  785.  
  786.           $Ltrim:     Remove leading spaces.
  787.  
  788.           $Rtrim:     Remove trailing spaces.
  789.  
  790.  
  791.    If Command
  792.  
  793.           You  can  do  comparisons  with  byte-type fields in numerous ways
  794.           using Suprtool.  These powerful features minimize  the  number  of
  795.           tasks  you must execute in order to select the data you need.  The
  796.           fewer the number of tasks, the faster your data  is  delivered  to
  797.           the users and applications that need it.
  798.  
  799.           You  can  combine  byte-type  fields together and use the built-in
  800.           string functions to create string expressions.  String expressions
  801.           involve  the  + operator and any of the built-in string functions,
  802.           which are $lower, $upper, $trim, $ltrim and $rtrim.
  803.  
  804.  
  805.    Fixed vs.  Variable Length Strings
  806.  
  807.           String comparisons  are  done  using  fixed-  and  variable-length
  808.           strings.   For  most  users, there should be no difference between
  809.           the two types of strings.  When doing string comparisons, Suprtool
  810.           always pads shorter strings with spaces, with the one exception of
  811.           comparing two fixed-length fields (see "Byte Fields" below).
  812.  
  813.           String expressions involving the + operator or the $lower, $upper,
  814.           $trim,  $ltrim  and  $rtrim  built-in  functions  are  done  using
  815.           variable-length strings.  Suprtool keeps track of  the  length  of
  816.           every  string, and all operations are done using the actual string
  817.           length.  For fields, the length of the string is the length of the
  818.           field.   If  you  do not want to retain all the spaces in a field,
  819.           use one of the built-in trimming functions.
  820.  
  821.           When creating string expressions,  string  constants  are  created
  822.           with  the  exact  length of the constant.  For example, the string
  823.           "abc" is three characters long and the string "a" is one.
  824.  
  825.  
  826.    Byte Fields
  827.  
  828.           For historical reasons, comparing two  byte-type  fields  to  each
  829.           other  is  a special case.  If the two fields are exactly the same
  830.           length, Suprtool  compares  them  completely.   If  one  field  is
  831.           shorter,  the  comparison  is  done for the length of the shortest
  832.           field.  Suprtool  does  not  check  for  spaces  in  the  trailing
  833.           characters of the longer field.  For example,
  834.  
  835.                >define  short, 1,10   {10-character field}
  836.                >define  long ,11,15   {15-character field}
  837.                >if      short = long
  838.  
  839.           In this example, Suprtool compares the 10 bytes in the short field
  840.           with the first 10 bytes of the long field, but  ignores  the  last
  841.           five bytes of the long field.  If the expression on either side of
  842.           the equal sign consisted of more  than  one  field  (using  the  +
  843.           operator)  or  involved any of the built-in string functions, such
  844.           as $lower, $upper, $trim, $ltrim and $rtrim, Suprtool  would  have
  845.           compared both sides of the equal sign by padding the shorter field
  846.           with spaces.  It is only the case where you are directly comparing
  847.           one  byte-type  field  to another that Suprtool uses the length of
  848.           the shortest field for the comparison.
  849.  
  850.  
  851.    Trimming Spaces ($Trim, $Ltrim, $Rtrim)
  852.  
  853.           Use one of three built-in string functions to  remove  leading  or
  854.           trailing  spaces  from  a  string expression.  The three functions
  855.           are:
  856.  
  857.  
  858.           $Trim:      Remove leading and trailing  spaces  from  the  string
  859.                       expression.
  860.  
  861.           $Ltrim:     Remove leading spaces.
  862.  
  863.           $Rtrim:     Remove trailing spaces.
  864.  
  865.           Because  Suprtool  pads  shorter  strings  with  spaces when doing
  866.           comparisons, trimming  spaces  is  most  useful  when  creating  a
  867.           combined  string with several fields.  For example, you might want
  868.           to combine a person's first  and  last  name  (including  a  space
  869.           between the two):
  870.  
  871.                >if $trim(first) + " " + $trim(last) = "Joe Smith"
  872.  
  873.  
  874.    Mixed Case ($Upper and $Lower)
  875.  
  876.           By default, Suprtool does an exact match when comparing two string
  877.           expressions.  If the expressions vary  in  the  capitalization  of
  878.           characters,  Suprtool  will  find  them  unequal.   To do caseless
  879.           string comparisons or pattern matches, use the  $upper  or  $lower
  880.           functions.   Both  ASCII  and  Roman-8  characters  are shifted by
  881.           $upper and $lower.  For example,
  882.  
  883.                >if $upper(city) = "VANCOUVER"
  884.  
  885.                >if $lower(city) = "edmonton"
  886.  
  887.           Note that if you use the $upper or $lower functions, Suprtool does
  888.           not  shift  any  constants in the comparison.  You must explicitly
  889.           specify the constants in the correct case or you can use $upper or
  890.           $lower with the constant:
  891.  
  892.                >if $upper(city) = $upper("vancouver")
  893.  
  894.           Use  the $upper or $lower functions for caseless pattern matching.
  895.           As with other comparison operators, you must specify constants  in
  896.           the correct case when doing pattern matching:
  897.  
  898.                >if $upper(city) == "VAN@"
  899.  
  900.                >if $lower(city) == "ed@"
  901.  
  902.           You can use $upper and $lower with string expressions that combine
  903.           many fields and string functions.  In the  following  example,  we
  904.           create
  905.  
  906.                >if $read
  907.                -   $upper($trim(first) +
  908.                -             " "             +
  909.                -             $trim(last))
  910.                -   = "JOE SMITH"
  911.                -
  912.  
  913.  
  914.    Bugs Fixed in Version 4.4
  915.  
  916.  
  917.    Add Command.   The Add command no longer fails in the following cases:
  918.  
  919.           1. Extracting  byte-type  fields  with  constants  and the literal
  920.              string values are shorter than the length of the field.
  921.  
  922.           2. A self-describing file with more than  one  field  is  used  as
  923.              input.
  924.  
  925.  
  926.    Arithmetic  Operations.   Suprtool now has a better error message when an
  927.           arithmetic operation has an invalid decimal operand length.
  928.  
  929.  
  930.    Extract Command.    When  extracting  constants,   Suprtool   no   longer
  931.           incorrectly reports that the constant limit has been reached.
  932.  
  933.  
  934.    Extract Command.    When  extracting one field into another, invalid data
  935.           is no longer produced if the  two  fields  are  exactly  the  same
  936.           length  and  type,  but have a different number of implied decimal
  937.           places.
  938.  
  939.  
  940.    Extract Command.   When the  maximum  limit  of  extracted  constants  is
  941.           reached,  Suprtool  no  longer  incorrectly  reports the following
  942.           message:
  943.  
  944.            Error:  Number of constants in >EXTRACT exceeds maximum
  945.  
  946.           This error message has now been changed to:
  947.  
  948.            Error:  Total size of constants in >EXTRACT exceeds maximum
  949.  
  950.  
  951.  
  952.    Set Ignore On.    Suprtool  now  honors  the  Set  Ignore  On  flag  when
  953.           encountering  an  illegal  packed  decimal  number in the $stddate
  954.           function.
  955.