Setting up Unicode

To set up and use Unicode you must perform a particular procedure so the API registers a Unicode file space on the server and all file names in that file space become Unicode strings.

Restriction: You cannot store Unicode and non-Unicode file names in the same file space.

Compile the code with the -DUNICODE flag.
All strings in your application must be wchar strings.
Follow the structures in the tsmapitd.h file, and the function definitions in the tsmapifp.h file for calls to the API.
Set the useUnicode flag to bTrue on the tsmInitEx function call. Any new file space is registered as a Unicode file space.

When you send data to previously registered, non-Unicode file spaces, the API continues to send file names as non-Unicode. Rename the old file spaces on the server to fsname_old and start a new Unicode file space for new data. The API restores non-Unicode data from the old file spaces. Use the bIsUnicode field in the tsmQryRespFSData structure that is returned on a query file space to determine whether or not a file space is Unicode.

Each dsmXXX function call has a matching tsmXXX function call. The difference between the two are the structures that are used. All tsmXXX function call structures have dsChar_t types for string values when they are compiled with the UNICODE flag. The dsChar_r maps to wchar. There is no other difference between these interfaces.

Restriction: Use either one interface or the other. Do not mix the dsmXXX function call and tsmXXX function call interfaces. Ensure that you use the Tivoli® Storage Manager structures and Tivoli Storage Manager version definitions.

Some constants continue to be defined in the dsmapitd.h file, so you need both the dsmapitd.h and the tsmapitd.h files when you compile.

You can use the Tivoli Storage Manager interface on other operating systems, such as UNIX or Linux, but on these operating systems, the dsChar_t type maps to char because Unicode is supported on Windows operating systems. You can write only one variation of the application and compile on more than one operating system using the Tivoli Storage Manager interface. If you are writing a new application, use the Tivoli Storage Manager interface.

If you are upgrading an existing application:

Convert the dsmXXX function call structures and calls to the Tivoli Storage Manager interface.
Migrate existing file spaces.
Back up new file spaces with the useUnicode flag set to true.

Note: After you use a Unicode-enabled client to access a node, you cannot connect to the same node name with an older version of the API or with an API from another operating system. If your application uses cross-platform capability, do not use the Unicode flag. There is no cross-platform support between Unicode and non-Unicode operating systems.

When you enable the useUnicode flag, all string structures are treated as Unicode strings. On the server, only the following fields are true Unicode:

File space name
High level
Low level
Archive description

All remaining fields convert to mbcs in the local code page before they are sent to the server. Fields, such as nodename, are wchar strings. They must be valid in the current locale. For example, on a Japanese machine, you can back up files with Chinese names, but the node name must be a valid string in Japanese. The option file remains in the current code page. If you need to create a Unicode include-exclude list, use the inclexcl option with a file name and create a Unicode file with Unicode patterns in it.