All PML variables of type STRING hold their data in Unicode UTF8 format. Refer to Using Unicode Text for further information. Fully developed PML code should - if required to - interact with the user by means of forms, menus, and alert boxes. However, while you are still developing your PML code the facilities described here might be useful. The commands described here should normally only be typed interactively or included in a PML File on a temporary basis. None of these commands should remain in fully developed PML code. 11.1. Using Unicode Text
The PDMS command processor supports Unicode characters. All PML string variables support Unicode values. You can use Unicode characters in PML variable names, PML object form and gadget names, PML method and function names. Filenames and directory names can also contain foreign Unicode characters, but remember that you may have problems saving files with foreign Unicode names in some source management systems e.g. ClearCase, so be very wary about using this facility. At PDMS12.1 it is mandatory that PML Appware source files are stored (in order of preference) as:
1. Unicode UTF8 encoding with a BOM present.
2. Unicode UTF16 or UTF32 encoding (big-endian or little-endian) with a BOM present. 3. ASCII 7bit encoding – no BOM needed
Notes:
• Using Unicode encodings with a BOM means that your (multilingual) Appware can be read successfully anywhere.
• Restricting your characters to ASCII 7bit (32 – 127) means that your (restricted) Appware can be read successfully anywhere (this is a strict subset of Unicode).
• If you use 8-bit single byte non-Unicode characters e.g. degree sign ° (Latin1 encoding), Euro € (CP1252(ANSI) encoding), OE (CP1252(ANSI) encoding) etc. Then you will probably experience difficulty when trying to read your Appware with CADC_LANG set to Korean, Chinese, Japanese etc.
11.1.1. Textual File Handling
By default all sequential text files read by PDMS will be expected to be in UTF8 format with a Byte Order Mark (BOM) present to identify them. Similarly by default all sequential text files written by PDMS will be in Unicode UTF8 format with a BOM present. The following PDMS environment variables are available for users to modify how PDMS handles sequential text files:
CADC_LANG specifies file encoding for reading PDMS external files which do not have an expected Unicode BOM present. If the variable is unset, then default to LATIN1 format. Files with the following Unicode BOMs will be translated to UTF8 on reading: UTF16 little-endian, UTF16 big-endian, UTF32 little-endian, UTF32 big-endian.
CADC_LANG_NEW specifies the file encoding for new files written by PDMS. If the variable is unset, then default to Unicode UTF8 format with a BOM present. The following encodings are currently supported:
• Unicode
• UTF8 Unicode UTF8
• UTF16LE UTF16 little-endian
• UTF16BE UTF16 big-endian
• UTF32BE UTF32 big-endian
• ISO
• LATIN1 ISO8859-1
• LATIN2 ISO8859-2
• LATIN5 ISO8859-5 Cyrillic
• Windows code page
• CP932 Japanese shift-JIS
• CP936 Simplified Chinese GBK
• CP949 Korean
• CP950 Traditional Chinese Big5
• CP1250 Central European
• CP1251 Cyrillic
• CP1252 LATIN1 + some extras (beware)
• For backwards compatibility with legacy PDMS Projects
• JAPANESE Japanese shift-JIS
• CHINESE Simplified Chinese (EUC)
• KOREAN Korean (EUC)
• TCHINESE Traditional Chinese (used in Taiwan for example) (EUC) 11.1.2. File Transcoding Utility
PDMS provides a file transcoding utility transc.exe which users may find useful, particularly for moving files between PDMS12.1 and previous PDMS versions. Transc is a command line application to transcode files from one encoding to another, and can also be used to add or remove the BOM from existing UTF8 (or UTF16) files. The basic syntax is:
Transc -encoding> <input-file> -encoding> <output-file> See Transc - text file transcoding utility.doc for more details. 11.1.3. Using Unicode as the new PDMS Internal Format
The major design decision for the Unicode conversion of PDMS was to use (32bit) Unicode Scalar (US) instead of ASCII codes as it's integer character representation (holding 1 US character code per array element), and to use UTF8 format for its character byte strings, with up to 4 bytes to represent 1 character. The section below describes a few important properties of Unicode Scalars and the UTF8 format.
1. A Unicode scalar is a 32 bit integer code which uniquely represents a single Unicode character. Unicode assumes that the 32 bit range will cope uniquely with all the world's character sets.
2. For the ASCII character set (codes 32 to 127) the codes are equal to the Unicode scalar codes.
3. UTF8 encoding needs 1, 2, 3 or 4 bytes to represent a Unicode scalar. For UTF8 we need to be able to clearly distinguish the number of characters held and the number of bytes needed to represent them - as they cannot be assumed to be the same.
4. Within UTF8 the ASCII characters can always be found by a simple byte by byte search in either direction.
5. UTF8 allows the first byte of any adjacent character to be found by simple byte by byte search in either direction, and every first byte yields the number of bytes in the character. 6. After having found a UTF8 character first byte (which could be an ASCII character e.g. $, /, &, space, ~ etc.) then subsequent bytes of the character are never ASCII bytes. So when you've found an ASCII byte it is a genuine character and not part of another character.
11.2. PML Tracing
If a PML File does not appear to be running in the way you expect the easiest thing to do is to turn on PML Tracing with the command:
PML TRACE ON
With PML Tracing switched on, each of the PML lines executed is output to the parent window together with its line number. Additional tracing messages tell you when you have begun to process a new PML File and when it has finished. To turn off tracing type:
PML TRACE OFF
These commands can also be put into a PML File on a temporary basis. You can also turn PML tracing on by setting the Environment Variable PMLTRACE to ON before you start the program. For more precise control of PML tracing you can use the $R command. $R100 is the equivalent of PML TRACE ON and $R0 is the same as PML TRACE OFF. Type the command $HR for online help on how to use the $R command.
11.3. Diagnostic Messages From Within PML Files
It is often useful to output a line to the screen from within a running PML File to indicate that the execution of the program has reached a particular stage. Use the $P command: $P !Total is: $!Total and !Maximum is: $!Maximum
Note:
The use of $ to convert the value of a variable to a STRING. 11.4. Alpha Log
The alpha-log is a file containing a record of all the commands processed together with any text output and error messages. To start recording use one of the following commands: alpha log /filename $* to open a new file
alpha log /filename OVERWRITE $* to replace an existing file alpha log /filename APPEND $* to add to an existing file To finish recording and close the file use:
alpha log END
11.5. Alpha Log and PML Tracing
The alpha-log does not include standard PML tracing from the command PML TRACE ON. For PML tracing to be included in the alpha-log, PML tracing should be directed to the alpha-window. For example, to obtain standard PML tracing in the alpha-log use the command:
$R102
Refer to the online help given by $HR for other options. 11.6. Suspending a Running PML Macro
If you cannot find out what is going wrong by means of PML trace output or writing out the values of PML Variables, you may suspend a running PML File at a particular point by including the command:
$MYou
can then query the values of any PML Variables of interest and even change the values of some PML Variables. To resume processing of the suspended PML File type into the command line:
$M+
Use these facilities only for debugging and do not leave these commands in a finished PML File.
Note:
These facilities do not apply to PML Functions or methods. 11.7. Querying PML
A variety of queries are available to help diagnose problems. Typically you might type these queries into the command line whilst a PML File is suspended. Alternatively you could include any of these commands temporarily within a PML File.
11.7.1. Querying the Currently Running PML File Stack
If you are interested in the name of the currently running PML File and the other PML Files from which the current file was invoked use the command:
$QM
11.7.2. Querying the Values of PML Variables
The table below gives some useful commands for querying PML Variables.
Command Effect
q var !LocalName Queries the value of a specific local variable, use the command. q var LOCAL Queries the values of all local variables.
q var !!GlobalName Queries the value of a specific global variable. q var GLOBAL Queries the values of all global variables
q var !MyArray[1] Queries the value of a specific element of an array. q var !MyArray Queries the values of all elements of an array.
q var !MyArray.Size() Queries the number of elements currently in an array. 11.7.3. Querying What Can Be Typed Next
When you are typing commands into a macro or into a command line, you may not remember exactly what arguments are available or what other commands are related. You will find full details in the appropriate Reference Manuals to the module, but you can also ask the command processor what sort of command or commands it is expecting next by typing: $Q
This will produce a list of every valid command word or argument type that you may enter next. The list may be long and could include every valid command for the module that you are in. The $Q facility is also useful to establish what is allowed as the next component of a command. Type the beginning of the command sequence followed by $Q.