Distributed software platform construction for information appliances INSTRUCTION MANUAL (for distribution CD-ROM) June 2000 TRON ASSOCIATION ------------------------------------------------------------------------------ Japanese version is "manual.txt". ------------------------------------------------------------------------------ INDEX 1. Overview of this system 1.1 Overall Software Structure 1.2 Operating environment and Development Environment 2. Installation manual 2.1 Installing in Host Machine 2.1.1 Installing B-right/V development environment 2.1.2 Loading middleware group provided by this system 2.1.3 Developing an application using this system 2.1.4 Developing a CORBA application using this system 2.2 Installing in Target Machine 2.2.1 Preparing execution environment 2.2.2 Transferring and executing a program in target machine 3. HOW TO USE JTRON PLATFORM FUNCTION 3.1 ITRON Attach Class API Instructions 3.1.1 General description 3.1.2 Package name 3.1.3 General usage 3.1.4 Classes belonging to the package 3.1.5 Attach class description 3.1.5.1 Task 3.1.5.2 FixedMemoryPool 3.1.5.3 VariableMemoryPool 4.1.5.4 Semaphore 3.1.5.5 EventFlag 3.1.5.6 MailBox 3.1.5.7 MessageBuffer 3.1.5.8 Port 3.1.6 Creation information class 3.1.6.1 T_CMPF 3.1.6.2 T_CMPL 3.1.6.3 T_CSEM 3.1.6.4 T_CFLG 3.1.6.5 T_CMBX 3.1.6.6 T_CMBF 3.1.6.7 T_CPOR 3.1.7 Status class 3.1.7.1 T_RTSK 3.1.7.2 T_RMPF 3.1.7.3 T_RMPL 3.1.7.4 T_RSEM 3.1.7.5 T_RFLG 3.1.7.6 T_RMBX 3.1.7.7 T_RMBF 3.1.7.8 T_RPOR 3.1.8 Memory operation class 3.1.8.1 ItronMemory 3.1.8.2 ItronFixedMemory 3.1.8.3 ItronVariableMemory 3.1.8.4 Rendezvous 3.1.9 JTRON exception class 3.1.9.1 JTRONException 3.1.10 ITRON API compatible class 3.1.10.1 ItronApi 3.2 Shared Object Class API Instructions 3.2.1 General description 3.2.2 Package name 3.2.3 General usage 3.2.4 Classes belonging to the package and ITRON API 3.2.5 Shared object class description 3.2.5.1 Sharable 3.2.5.2 SharedObject 3.2.5.3 SharedObjectManager 3.2.5.4 SharedObjectManagerImpl 3.2.5.5 ShmEsception 3.2.5.6 ShmIllegalStateException 3.2.5.7 ShmTimeoutException 3.2.6 ITRON API description 3.2.6.1 jti_get_obj 3.2.6.2 jti_get_mem 3.2.6.3 jti_loc_obj 3.2.6.4 jti_unl_obj 3.2.6.5 jti_funl_obj 3.2.6.6 jti_get_thr 3.2.6.7 jti_isa_thr 3.2.6.8 jti_int_thr 3.2.6.9 jti_isi_thr 3.2.6.10 jti_sus_thr 3.2.6.11 jti_rsm_thr 3.2.6.12 jti_sta_thr 3.2.6.13 jti_thr_stp 3.2.6.14 jti_des_thr 3.2.6.15 jti_get_jpr 3.2.6.16 jti_set_jpr 3.2.6.17 jti_get_tgr 3.2.6.18 jti_des_tgr 3.2.6.19 jti_sus_tgr 3.2.6.20 jti_rsm_tgr 3.2.6.21 jti_stp_tgr 3.3 Stream Class API Instructions 3.3.1 General description 3.3.2 Package name 3.3.3 General usage 3.3.4 Classes belonging to the package and ITRON API 3.3.5 Stream class description 3.3.5.1 JtiDataStream 3.3.5.2 JtiDataStreamException 3.3.6 Stream API description 3.3.6.1 jti_cre_stm 3.3.6.2 jti_del_stm 3.3.6.3 jti_wri_stm 3.3.6.4 jti_rea_stm 3.3.6.5 jti_sht_stm 3.3.6.6 jti_ref_stm 4. HOW TO USE CORBA-RELATED FUNCTION 4.1 CORBA-Related Function Interface Specification 4.1.1 Resource setting 4.1.2 ORB 4.1.3 CORBA Object 4.1.4 POA 4.1.5 exception 4.1.6 memory 4.1.7 stub skeleton 4.1.8 Dynamic entry 4.2 IOR Creation Command 5. HOW TO USE GUI MIDDLEWARE FUNCTION 5.1 GUI Middleware Function Outline 5.1.1 Event management function 5.1.2 Panel management function - Drawing section 5.1.3 Panel management function - Scene/Panel section 5.1.4 Parts management function 5.1.5 Character input management function 5.1.6 Data box management function 5.2 GUI Middleware Function System Call List 5.2.1 Event management function system call 5.2.2 Panel management function - Drawing section system calls 5.2.3 Panel management function - Scene/Panel section system calls 5.2.4 Parts management function system calls 5.2.5 Character input management function system calls 5.2.6 Data box management function system calls 5.3 Evaluation Driver Appendix 1 GUI middleware function external specifications Appendix 1.1 Event Management Function Appendix 1.1.1 Event queue management function Appendix 1.1.2 Input device management function Appendix 1.2 Panel Management Function Appendix 1.2.1 Drawing environment management function Appendix 1.2.2 Line-drawing function Appendix 1.2.3 Rectangle-drawing function Appendix 1.2.4 Circle-drawing function Appendix 1.2.5 Character-drawing function Appendix 1.2.6 Bit-map-drawing function Appendix 1.2.7 Panel-displaying function Appendix 1.2.5 Character-drawing function Appendix 1.2.8 Panel-clearing function Appendix 1.3 Parts Management Function Appendix 1.3.1 Momentary switch management function Appendix 1.3.2 Alternate switch management function Appendix 1.3.2 Alternate switch management function Appendix 1.3.2 Alternate switch management function Appendix 1.3.3 Switch selector management function Appendix 1.3.4 Scroll selector management function Appendix 1.3.5 Serial selector management function Appendix 1.3.6 Volume management function Appendix 1.4 Character Input Management Function Appendix 1.4.1 Text box management function Appendix 1.5 Data Box Management Function Appendix 1.5.1 Data box registration function ------------------------------------------------------------------------------ ============================================================================== 1. Overview of this system ============================================================================== ------------------------------------------------------------------------------ 1.1 Overall Software Structure ------------------------------------------------------------------------------ Overall structure of the software provided by this development product (this system) is given in the figure 1.1. +----------------------------------------------------------------------+ | | | Application program for control of embedded system | | | +------------------------------+----------------------+----------------+ | | | | | JTRON ** | CORBA ** | | | platform functions | related functions | | | | | | | +-----------------------+--------------+ | | | | / | | GUI ** | | | / TCP/IP * | | middleware | | | Java Virtual * / protocol | | functions | | | Machine (JVM) / stack | | | | | / | | | | | / | | | +------+----------------+---------------------+-------+----------------+ | | | micro-ITRON specification OS | | (Realtime kernel) | | | +----------------------------------------------------------------------+ | | | DOS/V PC (x86 Hardware) * | | | +----------------------------------------------------------------------+ **: The software provided by this system * : Using existing product Figure Figure1.1 The software provided by this system The followings explain each item. (1) JTRON platform function In terms of software portability and network connection, Java execution environment is the most powerful solution. However, using Java alone is not appropriate for precise control of hardwares and realtime processing. By providing a platform which fuses Java execution environment and realtime kernel into one and by implementing an application which requires realtime response in realtime kernel and an application where Java's advantages take a good effect in Java execution environment, users can use the platform with these advantages combined. What aims to realize this is JTRON specification which standardizes the specification in TRON projects. There are two versions for JTRON specification; JTRON 1.0 specification which specification was opened to public at the end of 1997 and has been already commercialized and JTRON 2.0 specification which enhances linkage functions between micro-ITRON - Java. Here, we develop JTRON 2.0-specification OS. The following three types of communication mechanism between programs in Java execution environment and tasks in micro-ITRON specification-kernel are defined in JTRON 2.0 specification. These functions are implemented independently. +----------------------------------------------------------------------------+ |Type 1 : |A mechanism to call a system call of micro-ITRON-specification | | |kernel from a program in Java execution environment. micro-ITRON | | |resources will be accessible from Java programs. | |----------+-----------------------------------------------------------------| |Type 2 : |A mechanism to directly access an object in Java execution | | |environment from a task in micro-ITRON-specification kernel. | |----------+-----------------------------------------------------------------| |Type 3 : |A mechanism to perform stream communication between a program in | | |Java execution environment and a task in | | |micro-ITRON-specification kernel. | +----------------------------------------------------------------------------+ As more concrete development procedure, Java environment threads are mapped onto the tasks of micro-ITRON to realize each synchronization mechanism among Java threads with micro-ITRON synchronization mechanism. Although ChaiVM by HP is employed as Java byte code processing system (so called JVM - Java Virtual Machine) to realize JTRON-specification OS, it is transportable to another JVM since we are to reduce the JVM-implementation-dependent areas as much as possible. (2) CORBA-related function To ensure interactive connection in information appliances or network in automobile, it is necessary to support highly abstract communication as well as to standardize low-level network protocols. As a high-level communication protocol, a method to recognize information appliance function as an object to realize linkage operation of information appliance with object-to-object communication has been considered as the likeliest candidate. A specification which realizes this method is CORBA (The Common Object Request Broker : Architecture and Specification). Here, we develop softwares of high-level communication protocol processing system for linkage operation of information appliance based on CORBA, an object-oriented distributed platform. For networking electric appliances and automobile control systems, we have to be able to deal with networks with small circuit capacity such as a network using radio communication and power line. Moreover, a demand for realtime response is difficult to be realized since cost reduction is strictly required. Because existing internet protocols and CORBA involve various problems on these terms, here we especially aim to solve these problems and named this development function "embedded CORBA". Being more specific, we develop this function while focusing on solving various problems in applying CORBA to information appliances, which are to realize compact software, easy operation and object service interface for electric appliances, etc. (3) GUI middleware function Here we develop softwares for middleware which supports building compact and highly scalable GUI (Graphical User Interface). Generally, GUI function required for embedded devices and electric appliances is quite restricted. On the other hand, existing Windows system was developed, targeting mainly personal computers and workstations and thus, has overspecification. This creates a great deal of waste both in terms of processor processing ability and memory requirement. Moreover, necessary GUI functions for information appliances greatly vary depending on characteristics of applicable device, such as user interface function, display resolution and input device. If we adopt a policy to develop an individual software for each demand, it creates a disadvantage in terms of software maintenance cost. On the contrary, GUI middleware for micro-ITRON we develop here has a characteristic of being scalable or adaptable. Being more specific, we aim to modularize individual function and make these functions adaptable to develop a middleware which can be implemented for wide range of purposes. Internal structure of GUI middleware is divided into drawing module for display, GUI parts (such as switch) management module, a module to manage screens and panels, a module to manage information (events) from input device and so on. We design this function so that users can use only necessary modules from these modules and that individual module function can be optimized according to its purpose as well. Java also provides a module for GUI called awt. Therefore, in a sense, this function overlaps with awt. However, standard GUI module which functions in Java is often not applicable when it comes to size (compact) and scalability. On the other hand, GUI middleware we develop here has an advantage of being able to provide GUI functions to existing Windows system and small embedded devices where GUI environment is difficult to be implemented in Java. ------------------------------------------------------------------------------ 1.2 Operating environment and Development Environment ------------------------------------------------------------------------------ (1)Overall structure The operating environment and development environment of this system are shown in the figure 1.2 Target machine Host machine (Development environment) +--------------------------+ +---------------------------+ +-+ Programs ** | |Console for development | | | for evaluation | | Compiling and Control of| S | | and experiment | | program for evaluation | | | | | and experiment | o | +--------------------------+ | Teminal via RS232C | | | Target functions *** | | | f | | of development | |Compiler | | | used in experiment | | GCC (Ver 2.7.2.1 or later)| t | | CORBA related functions | | | | | GUI middleware functions | | | w -+ +-------+--------+---------+ +---------------------------+ | |Java * |TCP/IP *| | | | a | |Virtual|protocol| | | | | |Machine|stack | | | | r | |(JVM) | | | | OS: Solaris | | +-------+--------+ | | (Ver 2.5 or later) | e | | micro-ITRON 3.0 * | | | | | specification | | | +-+ realtime kernel | | | H +--------------------------+ +---------------------------+ a +-+ | | | r | | DOS/V PC | | | d -+ | | | SUN Ultra 1 | w | |--------------------------+ | or equivalent | a | |Intel EtherExpress PRO/10+| | | r +-+ (Network interface card) | | | e +--------------------------+ +---------+------+----------+ ^ ^ | | | |RS232C | | | +---------------------+ | | | | | <<------+-------------------------------------+---------------->> LAN(Ethernet 10Base-T, 10Mbps) *** : Software provided by this system ** : Software to be developed by users * : An existing product Figure 1.2 Operating environment and development environment of this system Among those shown above, host machine (development environment) hardware and software structures are shown below. Hardware : SUN Ultra 1 or equivalent, Memory : 64 MB or more, HDD : 2 GB or more Software : OS : Solaris (Ver 2.5 or later) Development language : GCC (Ver 2.7.2.1 or later) Network : Ethernet (TCP/IP) An application program created in a host machine is transferred to the target machine via LAN to be executed in the target machine. In addition, a communication terminal program which functions in a host machine (such as tip of UNIX) is connected to the serial port of the target machine via RS-232C line to order the startup of OS or execution of an application program by using CLI utility which functions in the target machine. Refer to appendix 4 of coupling test report for details on the CLI utility. The following explains the hardware and software structures of the target machine. (2) Hardware structure As for the operating environment, the hardware structure of the target machine is shown in the figure 1.3. +------------------------------------------------------+ | DOS/V PC | | * IBM-PC/AT compatible machine | | for Windows 95/Windows98 | +---+--------------------------------------------------+ | | +--------------------------------------+ +--+ CPU (Pentium or later) | | +--------------------------------------+ | | +--------------------------------------+ +--+ Main memory 64M bytes or more | | +--------------------------------------+ | | +--------------------------------------+ +--+ IDE HDD | | +--------------------------------------+ | | +--------------------------------------+ +--+ 101/104 keyboard (For Japanese) | | | | | | 106/109 keyboard (English) | | +--------------------------------------+ | | +--------------------------------------+ +--+ Serial port +------ RS-232C | +--------------------------------------+ | | +--------------------------------------+ +--+ PS/2 compatible mouse | | +--------------------------------------+ | | +--------------------------------------+ +--+ VGA (640 * 480 dots, 16 colors) | | | Graphic function specified | | | VESA BIOS 2.0 or later | | +--------------------------------------+ | | +--------------------------------------+ +--+Intel EtherExpress PRO/10 +---- Ethernet |(Network interface card) | (10Base-T,10Mbps) +--------------------------------------+ Figure 1.3 Hardware structure of the target machine (3) Software structure The software we develop here functions in micro-ITRON 3.0-specification realtime kernel. This means that all of JTRON platform function, CORBA-related function and GUI middleware function are implemented by using functions of micro-ITRON 3.0-specification realtime kernel and call realtime kernel functions as required. An existing product is used as micro-ITRON 3. 0-specification realtime kernel. The existing product is also used for Java Virtual Machine (JVM) and TCP/IP protocol stack sections. JVM not only provides a function to implement JTRON platform function, but also calls realtime kernel or TCP/IP protocol stack function when needed. Moreover, while TCP/IP protocol stack function is used to implement CORBA-related function, TCP/IP protocol stack calls LAN driver and LAN driver calls realtime kernel functions. The softwares actually used as an existing product described above are given below. JVM : ChaiVM3.0 by Hewlett-Packard (Ver 2.1 or later) micro-ITRON 3.0-specification realtime kernel : Cho-kanji (B-right/V R2) by Personal Media Corporation o While this is a BTRON-specification OS, it also contains ITRON (I-right/V) as its core and can be also used as an ITRON execution environment. TCP/IP protocol stack : Use functions included B-right/V In addition, an utility called "CLI" included in B-right/V is in use on the target machine side to order the execution of an application program or to refer to the internal status of the target machine. Refer to appendix 4 of coupling test report for details on the CLI utility. (D) Network configuration A part of "JTRON platform function" and "CORBA-related function" function in the environment where a client machine and a server machine are connected with LAN. This is described in the figure 1.4. 10-Mbps Ethernet (TCP/IP) is used to connect the client machine and the server machine. Target machine +--------------------------+ +--------------------------+ +-+ | | | S | | Application program ** | | Application program ** | | | | | | o | +--------------------------+ +--------------------------+ | | Some of JTRON *** | | Some of JTRON *** | f | | platform functions | | platform functions | | | Some of CORBA *** | | Some of CORBA *** | t | | related functions | | related functions | -+ +-------+--------+---------+ +-------+--------+---------+ w | |Java * |TCP/IP *| | |Java * |TCP/IP *| | | |Virtual|protocol| | |Virtual|protocol| | a | |Machine|stack | | |Machine|stack | | | |(JVM) | | | |(JVM) | | | r | +-------+--------+ | +-------+--------+ | | | micro-ITRON 3.0 * | | micro-ITRON 3.0 * | e | | specification | | specification | +-+ realtime kernel | | realtime kernel | H +--------------------------+ +--------------------------+ a +-+ | | | r | | DOS/V PC | | DOS/V PC | d -+ | | | | w | +--------------------------+ +--------------------------+ a | |Intel EtherExpress PRO/10+| |Intel EtherExpress PRO/10+| r +-+ (Network interface card) | | (Network interface card) | e +--------------------------+ +--------------------------+ ^ ^ ^ ^ | | RS232C RS232C | | | +---+--------------------+---+ | | | Development environment | | | | (SUN Ultra 1 or equivalent | | | +----------------------------+ | | | <<------+--------------------------------------+------>> Ethernet(10Base-T, 10Mbps) *** : Software provided by this system ** : Software to be developed by users * : An existing product Figure 1.4 Network environment ============================================================================== 2. Installation manual ============================================================================== "JTRON platform function", "CORBA-related function" and "GUI middleware function" provided by this system are so-called "middleware groups" and cannot be executed as an application alone. These middleware groups are provided as a library in development environment, etc. and become a load module which functions in the target machine by being linked together with an application program an user created. In this chapter, how to install these middleware groups in development environment is described first. Then, how to install an application program using the execution environment of this system or this function is described. ------------------------------------------------------------------------------ 2.1 Installing in Host Machine ------------------------------------------------------------------------------ 2.1.1 Installing B-right/V development environment Before installing the middleware group provided by this system, "B-right/V development environment (BV-GSDK: B-right/V GNU based Software Developer's Kit)" must have been installed in the host machine (SUN Ultra 1 or equivalent). How to obtain and install BV-GSDK is described in "Cho-kanji developer's site" indicated by the following URL. Follow the instructions given on the site and download BV-GSDK to be installed in the host machine. (Note that the CD-ROM also contains this "Cho-kanji development environment") Cho-kanji developer's site http://www.personal-media.co.jp/btron/developer/index.html o "Cho-Kanji" is the product name of B-right/V R2. 2.1.2 Loading middleware group provided by this system Load the following files from the CD-ROM. This operation adds the objects and header files of the middleware group (library group) provided by this system to the development environment of the host machine. Note that the base directory of the development environment (BV-GSDK) is indicated as "${BD}" and the directory where sources to develop an application are to be stored as "$BD/jcg" in the following explanation. In addition, "${CDROM}" in the following explanation indicates the directory where the file exists in the CD-ROM and is different according to the host machine environment. If individual files in the CD-ROM can be directly accessed, name such as "/cdrom/cdrom0" (host-dependent) should be written. If you expand the archive file (JCGPRG.TGZ) in the CD-ROM due to file name restriction of 8 + 3 characters, write the name of the directory where the archive file was expanded. o Common procedures - Create a directory "jcg" under ${BD}/include and copy header files *.h (such as libjcg.h) into "jcg". % mkdir ${BD}/include/jcg % cp ${CDROM}/INCLUDE/*.h ${BD}/include/jcg - Copy libjcg.a, programs for building JCG execution environment, to under ${BD}/lib/i386e/. % cp ${CDROM}/ENV/libjcg.a ${BD}/lib/i386e - Provide a directory to develop applications and create a directory "etc" under the directory to copy makerules into the directory "etc". The setting of BD in makerules should be modified according to the actual environment. % mkdir ${BD}/jcg % mkdir ${BD}/jcg/etc % cp ${CDROM}/INCLUDE/makerules ${BD}/jcg/etc o Procedures necessary for developing a embedded CORBA application - Copy the file libecb.a, a library of embedded CORBA development products, to under ${BD}/lib/i386e/. % cp ${CDROM}/LIB/libecb.a ${BD}/lib/i386e - Copy cre_ior, an IOR creation command for developing a CORBA application, to under ${BD}/jcg/etc. % cp ${CDROM}/LIB/cre_ior ${BD}/jcg/etc o Procedures necessary for developing a GUI middleware application - Copy the file libgui.a, a library of GUI middleware development products, to under ${BD}/lib/i386e/. % cp ${CDROM}/LIB/libgui.a ${BD}/lib/i386e The directory structure (related sections only) resulting from the operations above is given below. Base directory of the development environment (${BD}) | +----include | +------jcg (make directory jcg, and copy *h here) | | | +----corba.h | +----ecbasrv.h | +----ecbcfg.h | +----ecbcon.h | +----ecberr.h | +----ecbgiop.h | +----ecbinit.h | +----ecbmem.h | +----ecbmrshl.h | +----ecbobj.h | +----ecborb.h | +----ecbpoa.h | +----ecbseq.h | +----ecbtype.h | +----i_device.h | +----i_jt2ext.h | +----i_malloc.h | +----i_pload.h | +----i_socket.h | +----libgui.h | +----lib | +-----i386e | +----libecb.a (copy *.a here) | +----libjcg.a | +----libgui.a | ... | +----jcg +----etc | +----cre_ior (copy cre_ior here) | +----makerules (copy makerules here) | | +---- sources of application programs, etc. ... 2.1.3 Developing an application using this system The following explains the development procedure of a sample program "dt" with "GUI middleware function" as an example (refer to sample/draw/src/Makefile for dt). If an application program an user developed uses "GUI middleware function", the header file of "libgui.h" must be included in the source program of the application. In addition, "-lgui -ljcg" must be specified as a link option to link "libgui.a" and "libjcg.a". In case of the sample program "dt", "libgui.h" is included in the following line in "dt.h". #include Also, linking "libgui.a" and "libjcg.a" is specified in the following line in "Makefile". Execute "make" after making these specifications to obtain an application program "dt" where "GUI middleware function" is built in. 2.1.4 Developing a CORBA application using this system An user needs to create a program, including stub and skeleton, to develop an application with "CORBA-related function" of this system. A stub includes a process to marshal requests (operation arguments) to be sent from client side to server side, a process to send marshalled requests to server, a process to receive responses (return codes of operation) from server side and a process to unmarshal the responses received. A skeleton includes unmarshalling process for requests received, calling operations, marshalling process for the response for calling and a process to send marshalled responses to client. Moreover, a dynamically (while the target machine is running) registered new CORBA object needs functions such as download function for execution codes and linkage function for downloaded programs and thus, will depend on the device which implements the program. Therefore, users must develop download function and linkage function by themselves. Also, should an user use existing CORBA common services (such as naming service) or develop these services, a distributed object environment which is more transparent to network can be built. The following explains the development procedure using sample programs "long" and "dync" with "CORBA-related function" as examples. "long" is a sample program for CORBA objects which reside in the target machine on the server side, and a client side program and a server side program are provided. The client side obtains IOR by receiving IOR sent from the server side via socket I/F. "dync" is a sample program for dynamically (while the target machine on the server side is running) registered new CORBA objects, and a client side program and a server side program are provided. Dynamically registered new CORBA objects of the sample program "dync" link dynamically registered new CORBA objects together when creating the server side download module and download. IOR is linked together with the client side download module. This IOR is created by cre_ior, an IOR creation command. If an application program an user developed uses "CORBA-related function", the header file of "corba.h" must be included in the source program of the application. In addition, "-lecb -ljcg" must be specified as a link option to link "libecb.a" and "libjcg.a". In case of the sample programs "long" and "dync", "corba.h" is included in the following line in "test.h". #include Also, linking "libecb.a" and "libjcg.a" is specified in the following line in "Makefile". LOADLIBES += -lecb -ljcg In addition, an application program with "CORBA-related" function initializes "CORBA-related function" by using an initializing function ECORBA_init. Therefore, data to be initialized must be specified for that process. The sample program states those data in "config.h" and only the target name is specified in "makeinfo". The following is an example where dell1 is specified for server side target name and dell2 for client side target name in "makeinfo". SRV_HOST = dell1 CLI_HOST = dell2 Execute "mymake" after making these specifications to obtain an application program where "CORBA-related function" is built in. The following download module is obtained in the sample program "long". client side longc server side longs The following download module is obtained in the sample program "dync". client side dyncc server side dyncs ------------------------------------------------------------------------------ 2.2 Installing in Target Machine ------------------------------------------------------------------------------ 2.2.1 Preparing execution environment Prepare the execution environment to execute this system using the following procedure after installing Cho-Kanji (B-right/V R2) in the target machine. 1. Copy the files in the directory ENV/JCGENV on the CD-ROM onto the Windows (Windows95, Windows98 or so.) partition of the machine where Cho-Kanji (B-right/V R2.xxx) has been installed. 2. Start Cho-Kanji and select "File Conversion" in the gadget menu and drag JCGENV file copied on Windows partition onto Cho-Kanji. Select "No conversion (standard)" for conversion method. o Instead of procedure 1. and 2., you can also use "File Conversion" in Cho-Kanji to directly convert ENV/JCGENV file in the CD-ROM into a file in Cho-Kanji. 3. Select "System environment setting" in the gadget menu and display "Version" screen. Drag JCGENV converted above into the screen. A panel saying "Do you want to process "JCG execution environment" system registration?" appears. Press execution switch to register. Restart the system after registering. This software is the software for interface to provide ITRON execution environment. Select "Network environment setting" in accessories menu and complete network settings. Double-click "Accessories box" which appears in startup window and then double-click "Console" in the window appeared. Enter "debugmode 1" in the window appeared to switch to debug mode. [/SYS]% debugmode 1 + 0: DEBUGMODE 1 [/SYS]% Finally, select exit menu in the startup window and select "Update and exit", "Update and exit" and "Restart" to restart the system. The following prompt appears in console in debug mode. [/SYS]% 2.2.2 Transferring and executing a program in target machine Enter as follows and restart the system to change the OS of the target machine to ITRON mode (non-GUI mode). [/SYS]% ren STARTUP.CMD STARTUP [/SYS]% To return to the original mode (BTRON mode), enter as follows and restart the system. [/SYS]% ren STARTUP STARTUP.CMD [/SYS]% When the system starts in ITRON mode, a prompt of "[IMS]%" appears. Enter as "$cli" here to activate CLI. Refer to the instructions attached to "Cho-Kanji development environment" for details on CLI. [IMS]% $cli pid = 2 (pri = -1) << START cli : R1.100 >> 2000/1/17(Mon) 18:36:01 [/SYS]% First, load the network driver to download the program developed in the host machine to the target machine via ftp. This operation is not necessary if downloading is not to be done via ftp. [/SYS]% kerext tcpipmgr KEREXT tcpipmgr [1] c0212000 - c0242000 [/SYS]% kerext netdrv KEREXT netdrv [2] c01fb000 - c0201000 [/SYS]% Then, download the application program developed in the host machine by using this system. In the example below, an application program "dt" where "GUI middleware function" is built in is downloaded. [/SYS]% fget -uuser -ppass host:/dt/pcat/dt 220 u30 FTP server (UNIX(r) System V Release 4.0) ready. .......................................................- ............................... 887677 bytes transferred. (177535 Bytes/sec) [/SYS] When using GUI middleware function, also download keyboard/PD driver (gkbpd) as described below if necessary. [/SYS]% fget -uuser -ppass host:/gkbpd/pcat/gkbpd 220 u30 FTP server (UNIX(r) System V Release 4.0) ready. .. 26631 bytes transferd. (26631 Bytes/sec) [/SYS] Finally, execute the downloaded application program. When using GUI middleware function, keyboard/PD driver (LIB/gkbpd in the CD-ROM) must have been transferred to the target machine and executed if necessary. In the example below, an application program "dt" where "GUI middleware function" is built in is executed. [/SYS]% kerext gkbpd KEREXT gkbpd [3] c01f2000 - c01f6000 [/SYS]% kerext dt KEREXT dt [4] c0242000 - c0334000 [/SYS] When running an application program with "JTRON platform function", the interface library for ITRON application program (LIB/jt2ext in the CD-ROM) must have been also transferred to the target machine and executed. [/SYS]% kerext jt2ext When running a Java application program, JVM where "JTRON platform function" is built in (LIB/slimrt in the CD-ROM) must have been transferred to the target machine and be executed at the same time. [/SYS]% kerext slimrt o is a Java application name (extension : .class) to be executed. ============================================================================== 3. HOW TO USE JTRON PLATFORM FUNCTION ============================================================================== ------------------------------------------------------------------------------ 3.1 ITRON Attach Class API Instructions ------------------------------------------------------------------------------ 3.1.1 General description By using this ITRON attach class, you can create a Java object which corresponds to an ITRON kernel object. Moreover, by operating the created Java object, you can operate the corresponding original ITRON kernel object to use synchronization and communication functions of micro-ITRON-specification realtime kernel from Java program. The ITRON kernel objects this ITRON attach class can handle are the following 8 objects. (A) Task (B) Fixed-size memory pool (C) Variable-size memory pool (D) Semaphore (E) Eventflag (F) Mailbox (G) Message buffer (H) Port 3.1.2 Package name The package name is "jp.gr.itron.jtron.attach". 3.1.3 General usage How this ITRON attach class is to be used is described below. Step 1 : Create a Java object which corresponds to an ITRON kernel object from Java program. For this, you can create a new ITRON kernel object to correspond to a Java object or create a Java object which corresponds to an existing ITRON kernel object. Step 2 : The created Java object is corresponding to an ITRON kernel object. Because executing a method of the Java object will issue an micro-ITRON system call for the corresponding ITRON kernel object, you can use synchronization and communication functions of micro-ITRON-specification realtime kernel from Java. Step 3 : The result of executing a method is the result of issuing an micro-ITRON system call for the corresponding ITRON kernel object. If an error is issued for the micro-ITRON system call, error occurrence is notified to Java program, the startup source, by using Java exception function. There are the following three types of constructors. (A) Specifies an ITRON kernel object ID and creates a new ITRON kernel object to correspond to the ID. (B) Creates a new ITRON kernel object which has an ID allocated by micro-ITRON-specification realtime kernel to correspond to the ID without specifying an ITRON kernel object ID. (C) Specifies the ID of an existing ITRON kernel object to correspond to the ITRON kernel object. 3.1.4 Classes belonging to the package Roughly speaking, this ITRON attach class consists of the following 6 types of classes. (A) Class corresponding to ITRON kernel object (B) Class to specify ITRON kernel object creation information (C) Class to return ITRON kernel object reference information (D) Class to operate memory area (E) JTRON exception class (F) ITRON API-compatible class Hereinafter, above (A), (B) and (C) are referred to as attach class, creation information class and state reference class respectively. Here describes the class to operate memory area. For coordinated operation of ITRON application and Java program, the first address of the memory area has to be given in accordance with micro-ITRON system call to exchange data between ITRON application and Java program. However, Java does not allow the operation on the contents of an address by specifying the address. Therefore, we created a Java object corresponding to the memory area to enable operation on the corresponding memory area. The class for this is the class to operate memory area. JTRON exception class is an exception class generated when an error is issued during synchronization and communication with an ITRON kernel object while using this ITRON attach class. ITRON API-compatible class is a class to provide API compatible with an micro-ITRON system call as a Java static method without creating a Java object. Attack classes are shown below: (A)Task (B)FixedMemoryPool (C)VariableMemoryPool (D)Semaphore (E)EventFlag (F)MailBox (G)MessageBuffer (H)Port Classes to operate memory area are shown below: (A)ItronMemory (B)ItronFixedMemory (C)ItronVariableMemory (D)Rendezvous JTRON exception class is shown below: (A)JTRONException ITRON API-compatible class is shown below: (A)ItronApi Now here describes AttachBasic, the parent class of the attach class. AttachBasic has the following field and method. [Field] (A) int Id The ID of the original corresponding ITRON kernel object [METHOD] (A) public int getId() Returns the ID of the original corresponding ITRON kernel object. 3.1.5 Attach class description 3.1.5.1 Task (1) [Class (Super class)] public class Task extends AttachBasic (2) [Description] This class is used to manipulate ITRON tasks (3) [Field] No field (4) [Constructor] (A)public Task (int taskId) throws JTRONException Creates an object attached to an existing task with its task ID. (B)public Task (Thread thread) throws JTRONException Creates an object mapped to a thread with the thread. (5) [Method] (C)public static Task currentTask () throws JTRONException Creates an object attached to the task corresponding to the current thread. (D)public void start () throws JTRONException Starts the task, corresponds to sta_tsk. (E)public void terminate () throws JTRONException Terminates the task, corresponds to ter_tsk. (F)public void changePriority (int priority) throws JTRONException Change the current priority of the task, corresponding to chg_pri. (G)public void releaseWait () throws JTRONException Forcibly releases WAIT state, corresponding to rel_wai. (H)public T_RTSK referStatus () throws JTRONException Refers to the state of the task, corresponds to ref_tsk. (I)public void suspend () throws JTRONException Suspends the execution of the task, corresponds to sus_tsk. (J)public void resume () throws JTRONException Releases SUSPEND state of the task, corresponds to rsm_tsk. (K)public void forceResume () throws JTRONException Forcibly releases SUSPEND state of the task, corresponds to frsm_tsk. (L)public void sleep () throws JTRONException Causes the issuing task to sleep. (M)public void sleep (int tmout) throws JTRONException Causes the issuing task to sleep with an additional timeout feature. (N)public void wakeup () throws JTRONException Wakes up the task. (O)public int cancelWakeup () throws JTRONException Cancel wakeup requests, corresponds to can_wup. (P)public static void rotateReadyQueue (int priority) throws JTRONException Rotates tasks on the ready queue associated with the priority level specified by priority. (Q)public static int getTaskId () throws JTRONException Gets the ID of the issuing task. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. Thread specified in Task(Thread thread) has to have executed run() method, or it causes exception. 3.1.5.2 FixedMemoryPool (1) [Class (Super class)] public class FixedMemoryPool extends AttachBasic (2) [Description] This class is used to manipulate fixed length memory pool. (3) [Field] No field (4) [Constructor] (A)public FixedMemoryPool (int mpfid,int length) throws JTRONException Creates an abject attached to an existing fixed length memory pool (B)public FixedMemoryPool (int mpfid,T_CMPF cmpf) throws JTRONException Creates a new fixed length memory pool and an object specified with ID, attaches it to the memory pool. (C)public FixedMemoryPool (T_CMPF cmpf) throws JTRONException Creates a new fixed length memory pool and an object (without ID specification), attaches it to the memory pool. (5) [Method] (D)public void delete () throws JTRONException Deletes the fixed length memory pool, corresponds to del_mpf. (E)public ItronFixedMemory get () throws JTRONException Allocates a memory block from the fixed length memory pool, corresponds get_blf. (F)public ItronFixedMemory get (int tmout) throws JTRONException Allocates a memory block from the fixed length memory pool with an additional timeout feature, corresponds tget_blf. (G)public ItronFixedMemory poll () throws JTRONException Polls and allocates a memory block from the fixed length memory pool, corresponds pget_blf. (H)private T_RMPF referStatus () throws JTRONException Refers to the state of the fixed length memory pool, corresponds ref_mpf. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.5.3 VariableMemoryPool (1) [Class (Super class)] public class VariableMemoryPool extends AttachBasic (2) [Description] This class is used to manipulate variable length memory pool. (3) [Field] No field (4) [Constructor] (A)public VariableMemoryPool (int mplid) throws JTRONException Creates an abject attached to an existing variable length memory pool (B)public VariableMemoryPool (int mplid,T_CMPL cmpl) throws JTRONException Creates a new variable length memory pool and an object specified with ID, attaches it to the memory pool. (C)public VariableMemoryPool (T_CMPL cmpl) throws JTRONException Creates a new variable length memory pool and an object (without ID specification), attaches it to the memory pool. (5) [Method] (D)public void delete () throws JTRONException Deletes the variable length memory pool, corresponds to del_mpl. (E)public ItronVariableMemory get (int length) throws JTRONException Allocates a memory block from the variable length memory pool, corresponds get_blk. (F)public ItronVariableMemory get (int length,int tmout) throws JTRONException Allocates a memory block from the fixed length memory pool with an additional timeout feature, corresponds tget_blk. (G)public ItronVariableMemory poll (int length) throws JTRONException Polls and allocates a memory block from the fixed length memory pool, corresponds pget_blk. (H)public T_RMPL referStatus () throws JTRONException Refers to the state of the fixed length memory pool, corresponds ref_mpl (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 4.1.5.4 Semaphore (1) public class Semaphore extends AttachBasic (2) [Description] This class is used to manipulate ITRON semaphores. (3) [Field] No fields (4) [Constructor] (A)public Semaphore (int semId) throws JTRONException Creates an object attached to an existing semaphore. (B)public Semaphore (int semid,T_CSEM csem) throws JTRONException Creates a new semaphore and an object specified with ID, attaches it to the semaphore. (C)public Semaphore (T_CSEM csem) throws JTRONException Creates a new semaphore and an object (without ID specification), attaches it to the semaphore. (5) [Method] (D)public void delete () throws JTRONException Deletes the semaphore. (E)public void signal () throws JTRONException Returns one resource to the semaphore, corresponds to sig_sem. (F)public void waitSemaphore () throws JTRONException Obtains one resource from the semaphore, corresponds to wai_sem. (G)public void waitSemaphore (int tmout) throws JTRONException Obtains one resource from the semaphore with an additional timeout feature, corresponds to twai_sem. (H)public void poll () throws JTRONException Polls and obtains one resource from the semaphore, corresponds to pwai_sem. (I)public T_RSEM referStatus () throws JTRONException Refers to the state of the semaphore. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.5.5 EventFlag (1) [Class (Super class)] public class EventFlag extends AttachBasic (2) [Description] This class is used to manipulate event flags. (3) [Field] No field (4) [Constructor] (A)public EventFlag (int evfId) throws JTRONException Creates an object attached to an existing event flag. (B)public EventFlag (int evfid,T_CFLG cflg) throws JTRONException Creates a new event flag and an object specified with ID, attaches it to the event flag. (C)public EventFlag (T_CFLG cflg) throws JTRONException Creates a new event flag and an object (without ID specification), attaches it to the event flag. (5) [Method] (D)public void delete () throws JTRONException Deletes the event flag, corresponds def_flg. (E)public void set (int pattern) throws JTRONException Sets the bits of the eventflag, corresponds to set_flg. (F)public void clear (int pattern) throws JTRONException Clears the bits of the eventflag, corresponds to clr_flg. (G)public int waitFlag (int waitPattern,int waitMode) throws JTRONException Waits for the eventflag to be set to satisfy the wait release condition, corresponds to wai_flg. (H)public int waitFlag (int waitPattern,int waitMode,int tmout) throws JTRONException Waits for the eventflag to be set to satisfy the wait release condition with an additional timeout feature, corresponds to twai_flg. (I)public int poll (int waitPattern,int waitMode) throws JTRONException Polls the eventflag to be set to satisfy the wait release condition or not, corresponds to pol_flg. (J)public T_RFLG referStatus () throws JTRONException Refers to the state of the event flag. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.5.6 MailBox (1) [Class (Super class)] public class MailBox extends AttachBasic (2) [Description] This class is used to manipulate mailboxes. (3) [Field] No field (4) [Constructor] (A)public MailBox (int mbxId) throws JTRONException Creates an object attached to an existing mailbox. (B)public MailBox (int mbxid,T_CMBX cmbx) throws JTRONException Creates a new mailbox and an object specified with ID, attaches it to the mailbox. (C)public MailBox (T_CMBX cmbx) throws JTRONException Creates a new mailbox and an object (without ID specification), attaches it to the mailbox. (5) [Method] (D)public void delete () throws JTRONException Deletes the mailbox, corresponds del_mbx. (E)public void send (ItronMemory data) throws JTRONException Sends the message packet to the mailbox, corresponds to snd_mbx. (F)public ItronMemory receive (int length) throws JTRONException Receives a message from the mailbox, corresponds to rcv_mbx. (G)public ItronMemory receive (int length,int tmout) throws JTRONException corresponds to trcv_mbx. Receives a message from the mailbox with an additional timeout feature, (H)public ItronMemory pollReceive (int length) throws JTRONException Polls and receives a message from the mailbox, corresponds to prcv_mbx. (I)public T_RMBX referStatus () throws JTRONException Refers to the state of the event flag, corresponds to ref_mbx. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.5.7 MessageBuffer (1) [Class (Super class)] public class MessageBuffer extends AttachBasic (2) [Description] This class is used to manipulate the message buffer. (3) [Field] No field (4) [Constructor] (A)public MessageBuffer (int mbfId) throws JTRONException Creates an object attached to an existing message buffer. (B)public MessageBuffer (int mbfid,T_CMBF cmbf) throws JTRONException Creates a new message buffer and an object specified with ID, attaches it to the mailbox. (C)public MessageBuffer (T_CMBF cmbf) throws JTRONException Creates a new message buffer and an object (without ID specification), attaches it to the mailbox. (5) [Method] (D)public void delete () throws JTRONException Deletes the message buffer, corresponds del_mbf. (E)public void send (ItronMemory data) throws JTRONException Sends the message to the message buffer, corresponds to snd_mbf (F)public void send (ItronMemory data,int tmout) throws JTRONException Sends the message to the message buffer with an additional timeout feature, corresponds to tsnd_mbf (G)public void pollSend (ItronMemory data) throws JTRONException Polls and sends the message to the message buffer, corresponds to psnd_mbf (H)public ItronMemory receive (int length) throws JTRONException Receives the message from the message buffer, corresponds to rcv_mbf. (I)public ItronMemory receive (int length,int tmout) throws JTRONException Receives the message from the message buffer with an additional timeout feature, corresponds to trcv_mbf. (J)public ItronMemory pollReceive (int length) throws JTRONException Polls and receives the message from the message buffer, corresponds to prcv_mbf. (K)public void receiveWithMemory (ItronMemory data) throws JTRONException Receive message from the data area, corresponds to rcv_mbf. (L)public void receiveWithMemory (ItronMemory data,int tmout) throws JTRONException Receive message from the data area with an additional timeout featrure, corresponds to trcv_mbf. (M)public void pollReceiveWithMemory (ItronMemory data) throws JTRONException Polls and receive message from the data area, corresponds to prcv_mbf. (N)public T_RMBF referStatus () throws JTRONException Refers to the state of the message buffer, corresponds to ref_mbf. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.5.8 Port (1) [Class (Super class)] public class Port extends AttachBasic (2) [Description] This class is used to manipulate an ITRON port. (3) [Field] No field (4) [Constructor] (A)public Port (int portId) throws JTRONException Creates an object attached to an existing port. (B)public Port (int portid,T_CPOR cpor) throws JTRONException Creates a new port and an object specified with ID, attaches it to the port. (C)public Port (T_CPOR cpor) throws JTRONException Creates a new port and an object (without ID specification), attaches it to the port. (5) [Method] (D)public void delete () throws JTRONException Deletes the port, corresponds del_por. (E)public ItronMemory call (ItronMemory mem,int calptn,int csize) throws JTRONException Calls the specified port for a rendezvous, corresponds to cal_por. (F)public ItronMemory call (ItronMemory mem,int calptn,int csize,int tmout) throws JTRONException Calls the specified port for a rendezvous with an additional timeout feature, corresponds to tcal_por. (G)public ItronMemory pollAndCall (ItronMemory mem,int calptn,int csize) throws JTRONException Polls and calls the specified port for a rendezvous, corresponds to pcal_por. (H)public Rendezvous accept (int acpptn) throws JTRONException Accepts the specified port for a rendezvous, corresponds to acp_por. (I)public Rendezvous accept (int acpptn,int tmout) throws JTRONException Accepts the specified port for a rendezvous with an additional timeout feature, corresponds to tacp_por. (J)public Rendezvous pollAccept (int acpptn) throws JTRONException Polls and accepts the specified port for a rendezvous, corresponds to pacp_por. (K)public void forward (int calptn,Rendezvous data) throws JTRONException Forwards an accepted rendezvous to another port, corresponds to fwd_por. (L)public T_RPOR referStatus () throws JTRONException Refers to the state of the port, corresponds to ref_por. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6 Creation information class 3.1.6.1 T_CMPF (1) [Class (Super class)] public class T_CMPF (2) [Description] Fixed length memory pool creation information class (3) [Field] public int mpfatr; // memory pool attribute public int mpfcnt; // number of blocks of entire memory pool public int blfsz; // block size of fixed length memory (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6.2 T_CMPL (1) [Class (Super class)] public class T_CMPL (2) [Description] Variable length memory pool creation information class (3) [Field] public int mplatr; // memory pool attribute public int mplsz; // size of entire memory pool public static final int TA_FIFO = 0x0000; public static final int TA_TPRI = 0x0001; (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6.3 T_CSEM (1) [Class (Super class)] public class T_CSEM (2) [Description] Semaphore creation information class (3) [Field] public int sematr; // semaphore attribute public int isemcnt; /* semaphore initial value public int maxsem; /* semaphore maximum value public static final int TA_FIFO = 0x0000; // FIFO-ordered queuing of waiting tasks public static final int TA_TPRI = 0x0001; // Priority-ordered queuing of waiting tasks (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6.4 T_CFLG (1) [Class (Super class)] public class T_CFLG (2) [Description] Eventflag creation information class (3) [Field] public int flgatr; // eventflag attribute public int iflgptn; // initial value of eventflag public static final int TA_WSGL=0x00000000; // Waiting for multiple tasks is not allowed. public static final int TA_WMUL=0x00000008; // Waiting for multiple tasks is allowed. public static final int TWF_ANDW=0x00000000; // AND wait public static final int TWF_ORW=0x00000002; // OR wait public static final int TWF_CLR=0x00000001; // Clear specification (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6.5 T_CMBX (1) [Class (Super class)] public class T_CMBX (2) [Description] Mailbox creation information class (3) [Field] public int mbxatr; // mailbox attribute public int bufcnt; // size of ring buffer public static final int TA_TFIFO = 0x0000; public static final int TA_TPRI = 0x0001; public static final int TA_MFIFO = 0x0000; public static final int TA_MPRI = 0x0002; (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6.6 T_CMBF (1) [Class (Super class)] public class T_CMBF (2) [Description] Message Buffer creation information class. (3) [Field] public int mbfatr; // message buffer attribute public int bufsz; // size of message buffer public int maxmsz; // maximum size of message public static final int TA_TFIFO = 0x0000; public static final int TA_TPRI = 0x0001; (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.6.7 T_CPOR (1) [Class (Super class)] public class T_CPOR (2) [Description] Port creation information class (3) [Field] public int poratr; // port attribute public int maxcmsz; // maximum length of call message public int maxrmsz; // maximum length of reply message public static final int TA_NULL = 0x0000; (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7 Status class 3.1.7.1 T_RTSK (1) [Class (Super class)] public class T_RTSK (2) [Description] Task status class (3) [Field] public int tskpri; // current priority public int tskstat; // task status public int tskwait; // reason for wait public int wid; // waiting object ID public int wupcnt; // number of queued wakeup request public int suscnt; // number of nested SUSPEND request public int tskatr; // task attribute public int itskpri; // initial task priority public int stksz; // stack size public static final int TTS_RUN = 0x0001; // RUN public static final int TTS_RDY = 0x0002; // READY public static final int TTS_WAI = 0x0004; // WAIT public static final int TTS_SUS = 0x0008; // SUSPEND public static final int TTS_WAS = 0x000c; // WAIT-SUSPEND public static final int TTS_DMT = 0x0010; // DORMANT public static final int TTW_SLP = 0x0001; // waiting with slp_tsk or tslp_tsk public static final int TTW_DLY = 0x0002; // waiting with dly_tsk public static final int TTW_NOD = 0x0008; // waiting for connection function response public static final int TTW_FLG = 0x0010; // waiting with wai_flg public static final int TTW_SEM = 0x0020; // waiting with wai_sem public static final int TTW_MBX = 0x0040; // waiting with rcv_msg public static final int TTW_SMBF = 0x0080; // waiting with snd_mbf public static final int TTW_MBF = 0x0100; // waiting with rcv_mbf public static final int TTW_CAL = 0x0200; // waiting on rendezvous call public static final int TTW_ACP = 0x0400; // waiting on rendezvous accept public static final int TTW_RDV = 0x0800; // waiting on rendezvous completion public static final int TTW_MPL = 0x1000; // waiting with get_blk public static final int TTW_MPF = 0x2000; // waiting with get_blf (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.2 T_RMPF 1. [Class (Super class)] public class T_RMPF 2. [Description] Fixed length memory pool status class 3. [Field] public int wtsk; // waiting task information public int frbcnt; // number of blocks in free area 4. [Constructor] Default no-arg constructor. 5. [Method] No method 6. [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.3 T_RMPL (1) [Class (Super class)] public class T_RMPL (2) [Description] Variable length memory pool status class (3) [Field] public int wtsk; // waiting task information public int frsz; // total size of free area public int maxsz; // maximum size of contiguous free area (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.4 T_RSEM (1) [Class (Super class)] public class T_RSEM (2) [Description] Semaphore status class (3) [Field] public int wtsk; // waiting task information public int semcnt; // current semaphore count (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.5 T_RFLG (1) [Class (Super class)] public class T_RFLG (2) [Description] Event flag status class (3) [Field] public int wtsk; // waiting task information public int flgptn; // current event flag bit pattern (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.6 T_RMBX (1) [Class (Super class)] public class T_RMBX (2) [Description] Mailbox status class (3) [Field] public int wtsk; // waiting task information (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.7 T_RMBF (1) [Class (Super class)] public class T_RMBF (2) [Description] Message buffer status class (3) [Field] public int wtsk; // waiting task information public int stsk; // sending task information public int msgsz; // size of the message to be received next public int frbufsz; // size of free buffer (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.7.8 T_RPOR (1) [Class (Super class)] public class T_RPOR (2) [Description] Port status class (3) [Field] public int wtsk; // waiting task information public int atsk; // accepting task information (4) [Constructor] Default no-arg constructor. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.8 Memory operation class 3.1.8.1 ItronMemory (1) [Class (Super class)] public class ItronMemory extends AttachBasic (2) [Description] This class is used to operate memory area. (3) [Field] No field (4) [Constructor] (A)public ItronMemory (int len) throws JTRONException Creates a memory operation object with specified length. (B)public ItronMemory () Creates a memory operation object. [Method] (C)public void free () throws JTRONException Frees the memory area. (C)public int getLength () throws JTRONException Gets the length of the memory area (D)public void disableWrite () Disable to write on the memory area (E)public void enableWrite () Enable to write on the memory area (F)public boolean isWriteable () Returns the status of current write permission of the memory area. (G)public void seek (int offset) throws JTRONException Moves the memory access pointer to offset from the start. (H)public boolean checkSeek (int offset) Checks the offset is within the memory area or not. (I)public boolean checkEof () Checks the access Point is EOF or not. (J)public int read () Returns data from the current position. (K)public byte readByte () throws JTRONException Retrieves 1 byte length data from the current position. (L)public byte readByte (int offset) throws JTRONException Retrieves 1 byte length data from offset position. (M)public short readShort () throws JTRONException Retrieves Short length data from the current position. (N)public short readShort (int offset) throws JTRONException Retrieves Short length data from offset position. (O)public int readInt () throws JTRONException Retrieves Int length data from the current position. (P)public int readInt (int offset) throws JTRONException Retrieves Int length data from offset position. (Q)public long readLong () throws JTRONException Retrieves Long length data from the current position. (R)public long readLong (int offset) throws JTRONException Retrieves Long length data from offset position. (S)public int read (byte b[],int len) throws JTRONException Copies byte array from current position. (T)public int read (int offset,byte b[],int len) throws JTRONException Copies byte array from offset position. (U)public void writeByte (byte b) throws JTRONException write byte length data into current position. (V)public void writeByte (int offset,byte b) throws JTRONException Writes byte length data into the area starting from offset position. (W)public void writeShort (short s) throws JTRONException Writes Short length data into current position. (X)public void writeShort (int offset,short s) throws JTRONException Writes Short length data into the area starting from offset position. (Y)public void writeInt (int i) throws JTRONException Writes Int length data into current position. (Z)public void writeInt (int offset,int i) throws JTRONException Writes Int length data into the area starting from offset position. (AA)public void writeLong (long l) throws JTRONException Writes Long length data into current position. (AB)public void writeLong (int offset,long l) throws JTRONException Writes Long length data into the area starting from offset position. (AC)public int write (byte b[],int len) throws JTRONException Write byte array into current position (AD)public int write (int offset,byte b[],int len) throws JTRONException Write byte array into the area starting from offset position (5) [Remark] The differences between these specification and those of JTRON2.0 specification are described below: (A)It has the default no-arg constructor. (B)It has int read() method. (C)It has boolean checkSeek(int offset) method. (D)It has boolean checkEof() method. 3.1.8.2 ItronFixedMemory (1) [Class (Super class)] public class ItronFixedMemory extends ItronMemory (2) [Description] This class is used to manipulate memory area acquired from fixed length memory pool. (3) [Field] No field (4) [Constructor] This object is returned by a method of the attach class , FixedMemoryPool , which is associated with fixed length memory pool. (5) [Method] (B)public int getPoolId () Obtains the ID of the fixed length memory pool. (C)public void release () throws JTRONException Frees the memory area. (D)public void free () throws JTRONException Frees the memory area. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.8.3 ItronVariableMemory (1) [Class (Super class)] public class ItronVariableMemory extends ItronMemory (2) [Description] This class is used to manipulate memory area acquired from variable length memory pool. (3) [Field] No field (4) [Constructor] This object is returned by a method of the attach class , VariableMemoryPool , which is associated with variable length memory pool. (5) [Method] (B)public int getPoolId () Obtains the ID of the fixed length memory pool. (C)public void release () throws JTRONException Frees the memory area. (D)public void free () throws JTRONException Frees the memory area. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.8.4 Rendezvous (1) [Class (Super class)] public class Rendezvous extends ItronMemory (2) [Description] Memory operation class associated with rendezvous synchronization. (3) [Field] No field (4) [Constructor] No constructor (5) [Method] (A)public int getNo () Obtains the rendezvous number. (B)public void reply () throws JTRONException Terminates rendezvous synchronization, receives message. (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.9 JTRON exception class 3.1.9.1 JTRONException (1) [Class (Super class)] public class JTRONException extends Exception (2) [Description] This exception class is thrown in using a ITRON attach class because of error at synchronization and/or communication with the ITORN kernel object. (3) [Field] int exceptionCode // Exception code int resourceId // ID of attached ITRON kernel object int ApiNo // API number of micro-ITRON system call int ApiCls // API class number of micro-ITRON system call String ApiName // micro-ITRON system call name int ErrorCode // Error code String ErrorName // Error name (4) [Constructor] (A)JTRONException (String msg) Creates an object of the exception class with a message. (B)public JTRONException () Creates an object of the exception class. (5) [Method] No method (6) [Remark] There is no difference between these specification and those of JTRON2.0 specification. 3.1.10 ITRON API compatible class 3.1.10.1 ItronApi (1) [Class (Super class)] public class ItronApi (2) [Description] This class provides static methods which are compatible with micro-ITRON system calls, without creates Java object. (3) [Field] No field (4) [Constructor] No constructor (5) [Method] (A)public native static int dis_dsp () Disables dispatch, corresponds to ER dis_dsp(void). (B)public native static int ena_dsp () Enables dispatch, corresponds to ER ena_dsp(void). (C)public native static int chg_pri (int tskid,int tskpri) Changes task priority, corresponds to ER chg_pri(ID tskid, PRI tskpri). (D)public native static int rot_rdq (int tskpri) Rotates tasks on the ready queue, corresponds to ER rot_rdq(PRI tskpri). (E)public native static int rel_wai (int tskid) Releases wait of other task, corresponds to ER rel_wai(ID tskid). (F)public native static int get_tid (Integer tskid) Gets task IDentifier, corresponds to ER get_tid(ID *p_tskid). (G)public native static int ref_tsk (T_RTSK rtsk,int tskid) Refers task status, corresponds to ER ref_tsk(T_RTSK *pk_rtsk, ID tskid). (H)public native static int sus_tsk (int tskid) Suspends other task, corresponds to ER sus_tsk(ID tskid). (I)public native static int rsm_tsk (int tskid) Resumes suspended task, corresponds to ER rsm_tsk(ID tskid). (J)public native static int frsm_tsk (int tskid) Forcibly resumes suspended task, corresponds to ER frsm_tsk(ID tskid). (K)public native static int slp_tsk () Sleeps Task, corresponds to ER slp_tsk(void). (L)public native static int tslp_tsk (int tmout) Sleeps Task with timeout, crresponds to ER tslp_tsk(TMO tmout). (M)public native static int wup_tsk (int tskid) Wakes up other task, corresponds to ER wup_tsk(ID tskid). (N)public native static int can_wup (Integer wupcnt,int tskid) Cancels wakeup request, corresponds to ER can_wup(INT *p_wupcnt, ID tskid). (O)public native static int vcre_sem (T_CSEM csem) Creates semaphore without ID specification, corresponds to ER vcre_sem(T_CSEM *pk_csem). (P)public native static int cre_sem (int semid,T_CSEM csem) Creates semaphore with specified ID, corresponds to ER cre_sem(ID semid, T_CSEM *pk_csem) (Q)public native static int del_sem (int semid) Deletes semaphore, corresponds to ER del_sem(ID semid). (R)public native static int sig_sem (int semid) Signals semaphore, corresponds to ER sig_sem(ID semid). (S)public native static int wai_sem (int semid) Waits on semaphore, corresponds to ER wai_sem(ID semid). (T)public native static int preq_sem (int semid) Polls and requests semaphore, corresponds to ER preq_sem(ID semid). (U)public native static int twai_sem (int semid,int tmout) Waits on semaphore with timeout, corresponds to ER twai_sem(ID semid, TMO tmout). (V)public native static int ref_sem (T_RSEM rsem,int semid) Refers semaphore status, corresponds to ER ref_sem(T_RSEM *pk_rsem, ID semid). (W)public native static int vcre_flg (T_CFLG cflg) Creates eventflag without ID specification, corresponds to ER vcre_flg(T_CFLG *pk_cflg). (X)public native static int cre_flg (int flgid,T_CFLG cflg) Creates eventflag with specified ID, corresponds to ER cre_flg(ID flgid, T_CFLG *pk_cflg). (Y)public native static int del_flg (int flgid) Deletes eventflag, corresponds to ER del_flg(ID flgid). (Z)public native static int set_flg (int flgid,int setptn) Sets eventflag, corresponds to ER set_flg(ID flgid, UINT setptn). (AA)public native static int clr_flg (int flgid,int clrptn) Clears eventflag, corresponds to ER clr_flg(ID flgid,UINT clrptn). (AB)public native static int wai_flg (Integer flgptn,int flgid,int waiptn,int wfmode) Waits for eventflag, corresponds to ER wai_flg(UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode). (AC)public native static int pol_flg (Integer flgptn,int flgid,int waiptn,int wfmode) Waits for eventflag (Polling), corresponds to ER pol_flg(UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode). (AD)public native static int twai_flg (Integer flgptn,int flgid,int waiptn,int wfmode,int tmout) Waits for eventflag with timeout, corresponds to ER twai_flg(UINT *p_flgptn, ID flgid, UINT waiptn, UINT wfmode, TMO tmout). (AE)public native static int ref_flg (T_RFLG rflg,int flgid) Refers eventflag status, corresponds to ER ref_flg(T_RFLG *pk_rflg, ID flgid). (AF)public native static int vcre_mbx (T_CMBX cmbx) Creates mailbox without ID specification, corresponds to ER vcre_mbx(T_CMBX *pk_cmbx). (AG)public native static int cre_mbx (int mbxid,T_CMBX cmbx) Creates mailbox with specified ID, corresponds to ER cre_mbx(ID mbxid, T_CMBX *pk_cmbx). (AH)public native static int del_mbx (int mbxid) Deletes mailbox, corresponds to ER del_mbx(ID mbxid). (AI)public native static int snd_msg (int mbxid,ItronMemory mem) Sends message to mailbox, corresponds to ER snd_msg(ID mbxid, T_MSG *pk_msg) (AJ)public native static int rcv_msg (ItronMemory mem,int mbxid) Receives message from mailbox, corresponds to ER rcv_msg(T_MSG* *ppk_msg, ID mbxid) (AK)public native static int prcv_msg (ItronMemory mem,int mbxid) Polls and receives message from mailbox, corresponds to ER prcv_msg(T_MSG* *ppk_msg, ID mbxid). (AL)public native static int trcv_msg (ItronMemory mem,int mbxid,int tmout) Receives message from mailbox with timeout, corresponds to ER trcv_msg(T_MSG* *ppk_msg, ID mbxid, TMO tmout). (AM)public native static int ref_mbx (T_RMBX rmbx,int mbxid) Refers mailbox status, corresponds to ER ref_mbx(T_RMBX *pk_rmbx, ID mbxid). (AN)public native static int vcre_mbf (T_CMBF cmbf) Creates messagebuffer without ID specification, corresponds to ER vcre_mbf(T_CMBF *pk_cmbf). (AO)public native static int cre_mbf (int mbfid,T_CMBF cmbf) Creates messagebuffer with specified ID. corresponds to ER cre_mbf(ID mbfid, T_CMBF *pk_cmbf). (AP)public native static int del_mbf (int mbfid) Deletes messagebuffer, corresponds to ER del_mbf(ID mbfid). (AQ)public native static int snd_mbf (int mbfid,ItronMemory mem,int size) Sends message to messagebuffer, corresponds to ER snd_mbf(ID mbfid, VP msg, INT msgsz). (AR)public native static int psnd_mbf (int mbfid,ItronMemory mem,int size) Polls and sends message to messagebuffer, corresponds to ER psnd_mbf(ID mbfid, VP msg, INT msgsz). (AS)public native static int tsnd_mbf (int mbfid,ItronMemory mem,int size,int tmout) Sends message to messagebuffer with timeout, corresponds to ER tsnd_mbf(ID mbfid, VP msg, INT msgsz, TMO tmout) (AT)public native static int rcv_mbf (ItronMemory mem,Integer size,int mbfid) Receives message from messagebuffer, corresponds to ER rcv_mbf(VP msg, INT *p_msgsz, ID mbfid). (AU)public native static int prcv_mbf (ItronMemory mem,Integer size,int mbfid) Polls and receives message from messagebuffer, corresponds to ER prcv_mbf(VP msg, INT *p_msgsz, ID mbfid). (AV)public native static int trcv_mbf (ItronMemory mem,Integer size,int mbfid,int tmout) Receives message from messagebuffer with timeout, corresponds to ER trcv_mbf(VP msg, INT *p_msgsz, ID mbfid, TMO tmout). (AW)public native static int ref_mbf (T_RMBF rmbf,int mbfid) Refers messagebuffer status, corresponds to ER ref_mbf(T_RMBF *pk_rmbf, ID mbfid). (AX)public native static int loc_cpu () Locks CPU, corresponds to ER loc_cpu(void). (AY)public native static int unl_cpu () Unlocks CPU, corresponds to ER unl_cpu(void). (AZ)public native static int dis_int (int eintno) Disables interrupt. (BA)public native static int ena_int (int eintno) Enables interrupt. (BB)public native static int vcre_mpl (T_CMPL cmpl) Creates variable length memory pool without ID specification, corresponds to ER vcre_mpl(T_CMPL *pk_cmpl). (BC)public native static int cre_mpl (int mplid,T_CMPL cmpl) Creates variable length memory pool with specified ID, corresponds to ER cre_mpl(ID mplid, T_CMPL *pk_cmpl). (BD)public native static int del_mpl (int mplid) Deletes variable length memory pool, corresponds to ER del_mpl(ID mplid) (BE)public native static int get_blk (ItronMemory mem,int mplid,int size) Gets variable length memory block, corresponds to ER get_blk(VP *p_blk, ID mplid, INT blksz) (BF)public native static int pget_blk (ItronMemory mem,int mplid,int size) Polls and gets variable length memory pool, corresponds to ER pget_blk(VP *p_blk, ID mplid, INT blksz). (BG)public native static int tget_blk (ItronMemory mem,int mplid,int size,int tmout) Gets variable length memory block with timeout, corresponds to ER tget_blk(VP *p_blk, ID mplid, INT blksz, TMO tmout). (BH)public native static int rel_blk (int mplid,ItronMemory mem) Releases variable size memory block, corresponds to ER rel_blk(ID mplid, VP blk). (BI)public native static int ref_mpl (T_RMPL rmpl,int mplid) Refers variable length memorypool status, corresponds to ER ref_mpl(T_RMPL *pk_rmpl, ID mplid). (BJ)public native static int vcre_mpf (T_CMPF cmpf) Creates fixed length memory pool without ID specification, corresponds to ER vcre_mpf(T_CMPF *pk_cmpf). (BK)public native static int cre_mpf (int mpfid,T_CMPF cmpf) Creates fixed length memory pool with specified ID. corresponds to ER cre_mpf(ID mpfid, T_CMPF *pk_cmpf). (BL)public native static int del_mpf (int mpfid) Deletes fixed length memory pool, corresponds to ER del_mpf(ID mpfid). (BM)public native static int get_blf (ItronMemory mem,int mpfid) Gets fixed length memory block, corresponds to ER get_blf(VP *p_blf, ID mpfid). (BN)public native static int pget_blf (ItronMemory mem,int mpfid) Polls and gets fixed length memory block, corresponds to ER pget_blf(VP *p_blf, ID mpfid). (BO)public native static int tget_blf (ItronMemory mem,int mpfid,int tmout) Gets fixed memory block with timeout, corresponds to ER tget_blf(VP *p_blf, ID mpfid, TMO tmout). (BP)public native static int rel_blf (int mpfid,ItronMemory mem) Release fixed length memory block, corresponds to ER rel_blf(ID mpfid, VP blf). (BQ)public native static int ref_mpf (T_RMPF rmpf,int mpfid) Refers fixed length memorypool status, corresponds to ER ref_mpf(T_RMPF *pk_rmpf, ID mpfid). (BR)public native static int vcre_por (T_CPOR cpor) Creates port for rendezvous without ID specification, corresponds to ER vcre_por(T_CPOR *pk_cpor). (BS)public native static int cre_por (int portid,T_CPOR cpor) Creates port for rendezvous with specified ID, corresponds to ER cre_por(ID porid, T_CPOR *pk_cpor). (BT)public native static int del_por (int portid) Deletes port for rendezvous, corresponds to ER del_por(ID porid). (BU)public native static int cal_por (ItronMemory mem,Integer rsize,int portid, int calptn, int csize) Calls port for rendezvous, corresponds to ER cal_por(VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT cmsgsz). (BV)public native static int pcal_por (ItronMemory mem,Integer rsize,int portid, int calptn, int csize) Polls and calls port for rendezvous, corresponds to ER pcal_por(VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT cmsgsz) (BW)public native static int tcal_por (ItronMemory mem,Integer rsize,int portid,intcalptn,int csize, int tmout) Calls port for rendezvous with timeout, corresponds to ER tcal_por(VP msg, INT *p_rmsgsz, ID porid, UINT calptn, INT cmsgsz, TMO tmout). (BX)public native static int acp_por (Integer rdvno,ItronMemory mem,Integer csize,int portid, int acpptn) Accepts port for rendezvous, corresponds to ER acp_por(RNO *p_rdvno, VP msg, INT * p_cmsgsz, ID porid, UINT acpptn) (BY)public native static int pacp_por (Integer rdvno,ItronMemory mem,Integer csize,int portid, int acpptn) Polls and accepts port for rendezvous, corresponds to ER pacp_por(RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT acpptn). (BZ)public native static int tacp_por (Integer rdvno,ItronMemory mem,Integer csize,int portid,int acpptn, int tmout) Accepts port for rendezvous with timeout, corresponds to ER tacp_por(RNO *p_rdvno, VP msg, INT *p_cmsgsz, ID porid, UINT acpptn,TMO tmout) (CA)public native static int fwd_por (int portid,int calptn,int rdvno,ItronMemory mem,int csize) Forwards rendezvous to other port, corresponds to ER fwd_por(ID porid, UINT calptn, RNO rdvno, VP msg, INT cmsgsz). (CB)public native static int rpl_rdv (int rdvno,ItronMemory mem,int rsize) Replies Rendezvous, corresponds to ER rpl_rdv(RNO rdvno, VP msg, INT rmsgsz). (CC)public native static int ref_por (T_RPOR rpor,int portid) Refers port status, corresponds to ER ref_por(T_RPOR *pk_rpor, ID porid). (CD)public native static int set_tim (long time) Sets system clock, corresponds to ER set_tim(SYSTIME *pk_tim). (CE)public native static int get_tim (Long time) Gets system clock and returns current system time, corresponds to ER get_tim(SYSTIME *pk_tim). (6) [Remark] The differences between these specification and those of JTRON2.0 specification are described below: (A) Method set_tim() and get_tim() do not use class SYSTIME, but use Long. ------------------------------------------------------------------------------ 3.2 Shared Object Class API Instructions ------------------------------------------------------------------------------ 3.2.1 General description By using this shared object class, you can exchange data between an ITRON application task and a Java program via shared objects. Registering a Java object to be shared in shared object manager in Java program allows access to the Java object from an ITRON application program. In addition, this allows exclusive control on shared objects from Java program or the ITRON application task to maintain data consistency of the shared object. Moreover, this allows an ITRON application task to call an execution control method involving state transition among Java Thread classes and ThreadGroup classes to control Java thread and Java thread group. Below shows relationship among a shared object, an micro-ITRON realtime task and a Java thread. +-------------+ Lock +-----------------+ Lock +----------+ | |--------=>| |<=--------| | | | Access | Shared Object | Access | | | micro-ITRON |<=------=>| |<=------=>| Java | | realtime | Unlock | | Unlock | thread | | task |--------=>| |<=--------| | | | +-----------------+ | | | | Thread / Threadgroup operation | | | |-------------------------------------=>| | +-------------+ +----------+ Figure 3.1 : Relationship among shared object, micro-ITRON realtime task and Java thread o Java is a registered trademark of Sun Microsystems, Inc., of U.S.A. in U.S. A. and other countries. o A thread is an unit of process which always takes place when Java program is activated. o A thread group is a set of threads. o A method refers to a function in object-oriented programming. o API (Application Programming Interface) is an interface between an operating system and an application program which operates in the OS. 3.2.2 Package name The classes to use shared object from Java side are bundled together in the following package. jp.gr.itron.jtron.shared 3.2.3 General usage The summary of how this shared object class is to be used is described below. 1. : In Java program, create a Java object which inherits SharedObject class and register the Java object in the shared object manager. 2. : In Java program, create a thread and suspend the thread. 3. : In an ITRON application task, obtain the shared object identification number by using jti_get_obj. 4. : In the ITRON application task, lock the shared object with jti_loc_obj. 5. : In the ITRON application task, obtains the JNI interface pointer and reference of the shared object by using jti_get_mem. 6. : In the ITRON application task, access to the field data of the shared object by using the JNI interface pointer and shared object reference obtained in the step 5 and JNI function. 7. : In the ITRON application task, unlock the shared object with jti_unl_obj. 8. : In the ITRON application task, obtain the thread identification number by using jti_get_thr. 9. : In the ITRON application task, resume the Java program thread suspended in the "step 2" by using jti_rsm_thr. 10. : In the Java program thread, lock the shared object by using lock method of SharedObject class. 11. 11 : In the Java program thread, access to the field data of the shared object. 12. : In the Java program thread, unlock the shared object by using unlock method of SharedObject class. 13. : In Java program, end sharing of the Java object by using unshare method of SharedObject class (the Java object is deleted from the registration in the shared object manager). 3.2.4 Classes belonging to the package and ITRON API The classes to operate shared objects from the java side are shown below : (A) Sharable (B) SharedObject (C) SharedObjectManager (D) SharedObjectManagerImpl (E) ShmException (F) ShmIllegalStateException (G) ShmTimeoutException The APIs to operate shared objects from the ITRON side are shown below : (A) jti_get_obj (B) jti_get_mem (C) jti_loc_obj (D) jti_unl_obj (E) jti_funl_obj The APIs to operate threads from the ITRON side are shown below : (A) jti_get_thr (B) jti_isa_thr (C) jti_int_thr (D) jti_isi_thr (E) jti_sus_thr (F) jti_rsm_thr (G) jti_sta_thr (H) jti_thr_stp (I) jti_des_thr (J) jti_get_jpr (K) jti_set_jpr (L) jti_get_tgr (M) jti_des_tgr (N) jti_sus_tgr (O) jti_rsm_tgr (P) jti_stp_tgr 3.2.5 Shared object class description 3.2.5.1 Sharable (1) [Class (Super class)] public interface Sharable (2) [Description] Provides the interface for the shared objects. The class of the object which is to be used as a shared object must implement this interface. (3) [Field] No field (4) [Constructor] No constructor (5) [Method] (A)public abstract void lock () throws ShmIllegalStateException Locks the shared object. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON realtime task, the method will be blocked until the object is unlocked. (B)public abstract void lock (int timeout) throws ShmTimeoutException, ShmIllegalStateException Locks the shared object with the additional timeout feature. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON realtime task, the method will be blocked for the timeout (unit ms), timeout time, until the object is unlocked. If the time-out time has elapsed, a ShmTimeoutException will be thrown. (C)public abstract void unlock () throws ShmIllegalStateException Unlocks the object locked by the same thread. No action takes place if the object has been unlocked. Throws a ShmIllegalStateException for the object which has been locked by a different thread or the micro-ITRON real-time task. (D)public abstract void forceUnlock () throws ShmIllegalStateException Unlocks the object which has been locked by a thread by force. No action takes place for the object being locked by the micro-ITRON real-time task. (E)public abstract void unshare () throws ShmIllegalStateException Terminates the object sharing with the micro-ITRON real-time task. If the object has been locked by a thread or the micro-ITRON real-time task, the method is blocked until the object is unlocked and terminates the sharing after the object is unlocked. If the sharing has been terminated, a ShmIllegalStateException will be thrown. (F)public abstract void unshare (int timeout) throws ShmTimeoutException, ShmIllegalStateException Terminates the object sharing with the real-time task with the additional timeout feature. If the object has been locked by a different thread or the realtime task, the method is blocked for the timeout (unit ms), time-out time, until the object is unlocked. If the time-out time has elapsed, a ShmTimeoutException will be thrown. The method terminates the sharing after the object is unlocked. If the sharing has been terminated, a ShmIllegalStateException will be thrown. (G)public abstract Object getContent () Returns the shared object. The SharedObjectManager actually obtains the shared object by using this method. (6) [Remark] No remark 3.2.5.2 SharedObject (1) [Class (Super class)] public class SharedObject extends Object implements Sharable (2) [Description] A shared object class. Programmers can easily create a shared object class by defining a subclass which inherits this class. (3) [Field] shm protected Aharable // The reference to the current shared object. (4) [Constructor] (A) public SharedObject (String name) throws ShmIllegalStateException Creates a shared object with name. The shared object is registered in the shared object manager when being created and the access to the object from the micro-ITRON realtime task will be enabled. If the registration fails, a ShmIllegalStateException will be thrown. (B) public SharedObject (Sharable shm, String name) throws ShmIllegalStateException Sets the shm, the object of the class implementing Sharable, as shared objects with name. The object will be registered in the manager when being created and the object can be referred to from the micro-ITRON real-time task. If the registration fails, a ShmIllegalStateException will be thrown. (5) [Method] (C) public void lock () throws ShmIllegalStateException Locks the shared object. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON realtime task, the method is blocked until the object is unlocked. (D) public void lock (int timeout) throws ShmIllegalStateException, ShmTimeoutException Locks the object with the additional timeout feature. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the real-time task, the method is blocked for the timeout (unit ms), time-out time, until the object is unlocked. If the time-out time has elapsed, a ShmTimeoutException will be thrown. (E) public void unlock () throws ShmIllegalStateException Unlocks the object locked by the same thread. No action takes place if the object has been unlocked. Throws a ShmIllegalStateException for the object which has been locked by a different thread or the real-time task. (F) public void forceUnlock () throws ShmIllegalStateException Unlocks the object which has been locked by a thread by force. No action takes place for the object being locked by the micro-ITRON real-time task. (G) public void unshare () throws ShmIllegalStateException Terminates the object sharing with the micro-ITRON realtime task side. If the object has been locked by a thread or the micro-ITRON real-time task, the method is blocked until the object is unlocked and terminates the sharing after the object is unlocked. If the sharing has been terminated, a ShmIllegalStateException will be thrown. (H) public void unshare (int timeout) throws ShmIllegalStateException, ShmTimeoutException Terminates the object sharing with the micro-ITRON realtime task. If the object has been locked by a different thread or the micro-ITRON realtime task, the method blocked for the timeout (unit ms), until the object is unlocked. If the time-out time has elapsed, a ShmTimeoutException will be thrown. The method terminates the sharing after the object is unlocked. If the sharing has been terminated, a ShmIllegalStateException will be thrown. (I) public Object getContent () Returns the shared object. The SharedObjectManager actually obtains the shared object by using this method. In the SharedObject, this method returns the Sharable object specified by the argument of a constructor (In this implementation, getContent() returns the instance variable shm). A programmer can override this method if the programmer would like to have another object (such as array) as the sharing target in the SharedObject sub class. (6) [Remark] Shared object name should be within 63 characters in UTF-8 code character strings. o UTF-8 (UCS transformation format 8-bit form) is an encoding method of Unicode characters. This is a variable-length encoding method where number of bytes represented by a character varies depending on the character. An ASCII character represents 1 byte. 3.2.5.3 SharedObjectManager (1) [Class (Super class)] public abstract class SharedObjectManager extends Object (2) [Description] The class to manage the shared objects. This class is in charge of the interface with the micro-ITRON real-time task. (3) [Field] No field (4) [Constructor] (A)protected SharedObjectManager () Creates the shared object manager. (5) [Method] (B) public static SharedObjectManager getSharedObjectManager () throws ShmIllegalStateException Returns the manager object of the default shared object. If the manager cannot be provided or is illegal, a ShmIllegalStateException will be thrown. (C) public abstract void share (Sharable obj, String name) throws ShmIllegalStateException Registers the obj, which implements Sharable, under the specified shared object name name. If it has been registered or the name is illegal, a ShmIllegalStateException will be thrown. (D) public abstract void unshare (String name) throws ShmIllegalStateException Deletes the shared object corresponding the specified shared object name. If the object does not exist, a ShmIllegalStateException will be thrown. (E) public abstract void unshare (String name, int timeout) throws ShmIllegalStateException, ShmTimeoutException Deletes the shared object corresponding the specified shared object name with the additional timeout feature. If the object does not exist, a ShmIllegalStateException will be thrown. (F) public abstract void lock (Sharable obj) throws ShmIllegalStateException Locks the shared object. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON real-time task, the method is blocked until the object is unlocked. (G) public abstract void lock (Sharable obj, int timeout) throws ShmIllegalStateException, ShmTimeoutException Locks the shared object with the additional timeout feature. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON real-time task, the method is blocked until the object is unlocked. Time-out time (unit: ms) can be specified and the method is blocked for the timeout time until the object is unlocked. If the timeout time has elapsed, a ShmTimeoutException will be thrown. (H) public abstract void unlock (Sharable obj) throws ShmIllegalStateException Unlocks the object locked by the same thread. No action takes place if the object has been unlocked. Throws a ShmIllegalStateException for the object which has been locked by a different thread or the micro-ITRON real-time task. (I) public abstract void forceUnlock (Sharable obj) throws ShmIllegalStateException Unlocks the object locked regardless of which thread locked the object. No action takes place if the object has been unlocked. The method is to be used when the thread which locked the object died without unlocking the object. (6) [Remark] Shared object name should be within 63 characters in UTF-8 code character strings. 3.2.5.4 SharedObjectManagerImpl (1) [Class (Super class)] class SharedObjectManagerImpl extends SharedObjectManager (2) [Description] The class to manage the shared objects. This class is in charge of the interface with the micro-ITRON real-time task. This class is the implementing class of SharedObjectManager. (3) [Field] No field (4) [Constructor] (A)protected SharedObjectManagerImpl () Creates the shared object manager. (5) [Method] (B) public static SharedObjectManager getSharedObjectManager () throws ShmIllegalStateException Returns the manager object of the default shared object. If the manager cannot be provided or is illegal, a ShmIllegalStateException will be thrown. (C) public void share (Sharable obj, String name) throws ShmIllegalStateException Registers the obj, which implements Sharable, under the specified shared object name. If it has been registered or the name is illegal, a ShmIllegalStateException will be thrown. (D) public void unshare (String name) throws ShmIllegalStateException Deletes the shared object corresponding the specified shared object name. If the object does not exist, a ShmIllegalStateException will be thrown. (E) public void unshare (String name, int timeout) throws ShmIllegalStateException, ShmTimeoutException Deletes the shared object corresponding the specified shared object name with the additional timeout feature. If the object does not exist, a ShmIllegalStateException will be thrown. (F) public void lock (Sharable obj) throws ShmIllegalStateException Locks the shared object. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON real-time task, the method is blocked until the object is unlocked. (G) public void lock (Sharable obj, int timeout) throws ShmIllegalStateException, ShmTimeoutException Locks the shared object with the additional timeout feature. No action takes place if the object has been locked by the same thread. If the object has been locked by a different thread or the micro-ITRON real-time task, the method is blocked until the object is unlocked. Time-out time (unit: ms) can be specified and the method is blocked for the timeout time until the object is unlocked. If the timeout time has elapsed, a ShmTimeoutException will be thrown. (H) public void unlock (Sharable obj) throws ShmIllegalStateException Unlocks the object locked by the same thread. No action takes place if the object has been unlocked. Throws a ShmIllegalStateException for the object which has been locked by a different thread or the micro-ITRON real-time task. (I) public abstract void forceUnlock (Sharable obj) throws ShmIllegalStateException Unlocks the object locked regardless of which thread locked the object. No action takes place if the object has been unlocked. The method is to be used when the thread which locked the object died without unlocking the object. (6) [Remark] Shared object name should be within 63 characters in UTF-8 code character strings. 3.2.5.5 ShmEsception (1) [Class (Super class)] public class ShmException extends Exception (2) [Description] Reports the occurrence of the exception related to shared objects. This class is a superclass of all the exception classes in this package. (3) [Field] No field (4) [Constructor] (A) public ShmException () Creates a ShmException without any detailed message. (B) public ShmException (String msg) Creates a ShmException which has a specified detailed message, msg. (5) [Method] No method (6) [Remark] No remark 3.2.5.6 ShmIllegalStateException (1) [Class (Super class)] public class ShmIllegalStateException extends ShmException (2) [Description] It is thrown when a method is issued but the object is in illegal status disabling the execution of the method. (3) [Field] public static final int ILLEGAL_MANAGER = 1 // Illegal shared object manager public static final int OBJECT_IN_USE = 2 // The object has been already registered. public static final int OBJECT_NOEXIST = 3 // The object is not registered. public static final int ILLEGAL_NAME = 4 // Illegal name. public static final int OBJECT_UNSHARED = 5 // The object has not been shared. public static final int OBJECT_LOCKED = 6 // he object has been locked by another Java thread // or the micro-ITRON realtime task. public static final int SYSTEM_ERROR = 7 // Internal system error (4) (A) public ShmIllegalStateException (int cause) Creates the exception object for the specified cause. Gives the detailed cause of the exception to the parameter cause. (B) public ShmIllegalStateException (int cause, String msg) Creates the exception object which has the detailed message of the specified cause. Normally, the detailed cause of the exception is specified to the cause and he object name is specified to the msg. (5) [Method] (C) public int getCause () Returns the detailed cause of the exception. (6) [Remark] No remark 3.2.5.7 ShmTimeoutException (1) [Class (Super class)] public class ShmTimeoutException extends ShmException (2) [Description] Reports that the time-out time has elapsed. (3) [Field] No field (4) [Constructor] (A) public ShmTimeoutException () Creates a ShmTimeoutException without any detailed message. (B) public ShmTimeoutException (String msg) Creates a ShmTimeoutException which has a specified detailed message, msg. Normally, the object name is specified to the msg. (5) [Method] No method (6) [Remark] No remark 3.2.6 ITRON API description 3.2.6.1 jti_get_obj (1) [API] Finds the shared object identification number by using names. ER ercd = jti_get_obj (char *objnm, JNO *p_objno) (2) [Parameteres] char *objnm Shared object name to be processed (Character strings) JNO *p_objno Shared object identification number (Pointer) (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_OBJ Specified shared object does not exist. E_PAR Wrong parameter (objnm is a NULL pointer) (5) [Remark] Shared object name should be within 63 characters in ASCII code character strings. 3.2.6.2 jti_get_mem (1) [API] Returns the shared object address information of shared object which corresponds to the specified shared object (Whose class name is Sharable). ER ercd = jti_get_mem (JNO objno, JNI_PTR *p_addr) The access to the shared object is executed with the JNI interface pointer which is stored in the shared object address information structure JNI_PTR which is returned by this API, the reference to the shared object, and JNI functions. o JNI (Java Native interface) is a standard programming interface to call the platform-dependent native code from Java programs. (2) [Parameteres] JNO objno Shared object identification number to be processed. VP* p_addr Shared object address information. Members of JNI_PTR structure : env *JNIEnv JNI interface pointer. obj jobject Reference to the shared object. (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter (Illegal objno) E_OBJ Specified shared object does not exist. E_UNLOCK Not locked by issuing task. (5) [Remark] o The identification number of the target shared object should be the value obtained by jti_get_obj. o Lock the shared object with jti_loc_obj before calling this API. 3.2.6.3 jti_loc_obj (1) [API] Locks the specified Java object ER ercd = jti_loc_obj (JNO objno, TMO tmout) (2) [Parameters] JNO objno Shared object identification number to be processed. TMO tmout Timeout time (ms) (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter (Illegal objno) E_OBJ Specified shared object does not exist E_TMOUT Time-out takes place E_RLWAI Waiting status released by force E_DLT Sharing released (5) [Remark] The identification number of the target shared object should be the value obtained by jti_get_obj. 3.2.6.4 jti_unl_obj (1) [API] Unlocks the specified shared object ER ercd = jti_unl_obj (JNO objno) (2) [Parameter] JNO objno Shared object identification number (3) [Return value] ER ercd Error code (4) [Error code] E OK Normal termination E PAR Wrong parameter (Illegal objno) E OBJ Specified shared object does not exist, or an other task intends to unlock the object. (5) [Remark] The identification number of the target shared object should be the value obtained by jti_get_obj. 3.2.6.5 jti_funl_obj (1) [API] Unlocks the specified shared object by force ER ercd = jti_funl_obj (JNO objno) (2) [Parameters] JNO objno Shared object identification number (3) [Return value] ER ercd Error code (4) [Error code] E OK Normal termination E PAR Wrong parameter (Illegal objno) E OBJ Specified object does not exist. (5) [Remark] The identification number of the target shared object should be the value obtained by jti_get_obj. 3.2.6.6 jti_get_thr (1) [API] Gets the thread identification number by the name of Java thread. ER ercd = jti_get_thr (char *thrnm, JNO *p_thrno) (2) [Parameters] char *thrnm Java thread name (ASCII character strings) JNO *p_thrno Java thread identification number (Pointer) (3) [Return value] ER ercd Error code (4) [Error codes] E_OK Normal termination E_OBJ Specified Java thread does not exist. E_PAR Wrong parameter (5) [Remark] o Thread name should be within 31 characters in ASCII character strings. o Name the target Java thread always in Java program. 3.2.6.7 jti_isa_thr (1) [API] Calls the isAlive method in the Java Thread class ER_BOOL ercd = jti_isa_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed (3) [Return value] ER_BOOL ercd Return value of the method or an error code (4) [Error code] TRUE True FALSE False E_PAR Wrong parameter (Illegal thrno) (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.8 jti_int_thr (1) [API] Calls the interrupt method in the Java Thread class ER ercd = jti_int_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed (3) [Return value] ER ercd Error code (4) [Error code] E OK Normal termination E PAR Wrong parameter (Illegal thrno) (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.9 jti_isi_thr (1) [API] Calls the isInterrupted method in the Java Thread class ER_BOOL ercd = jti_isi_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed (3) [Return value] ER BOOL ercd Return value of the method or an error code. (4) [Error codes] TRUE True FALSE False E_PAR Wrong parameter (Illegal thrno) (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.10 jti_sus_thr (1) [API] Calls the suspend method in the Java Thread class ER ercd = jti_sus_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter (Illegal thrno) E_OBJ A security exception took place while executing the Java method (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.11 jti_rsm_thr (1) [API] Calls the resume method in the Java Thread class. ER ercd = jti_rsm_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed. (3) [Return value] ER ercd Error code (4) [Error code] E OK Normal termination E PAR Wrong parameter (Illegal thrno) E OBJ A security exception took place while executing the Java method (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.12 jti_sta_thr (1) [API] Calls the start method in the Java Thread class. ER ercd = jti_sta_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed. (3) [Return value] ER ercd Error code (4) [Error codes] E_OK Normal termination E_PAR Wrong parameter (Illegal thrno) E_OBJ A status violation took place while executing the Java method (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.13 jti_thr_stp (1) [API] Calls the stop method in the Java Thread class ER ercd = jti_thr_stp (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed. (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter E_OBJ A security exception or a NULL pointer exception took place while executing the Java method. (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.14 jti_des_thr (1) [API] Calls the destroy method in the Java Thread class. ER ercd = jti_des_thr (JNO thrno) (2) [Parameters] JNO thrno Java thread identification number to be processed (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter E_OBJ A security exception took place while executing the Java method. (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.15 jti_get_jpr (1) [API] Calls the getPriority method in the Java Thread class. ER ercd = jti_get_jpr (JNO thrno, INT *p_rslt) (2) [Parameters] JNO thrno Java thread identification number to be processed INT *p_rslt Returned thread priority (Pointer) (3) [Return value] ER ercd Error code (4) [Error code] E OK Normal termination E PAR Wrong parameter (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.16 jti_set_jpr (1) [API] Calls the setPriority method in the Java Thread class. ER ercd = jti_set_jpr (JNO thrno, INT newpri) (2) [Parameters] JNO thrno Java thread identification number to be processed. INT newpri Java thread priority to be set. (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter E_OBJ A security exception or a wrong argument exception took place while executing the Java method (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_thr. 3.2.6.17 jti_get_tgr (1) [API] Gets the Java thread group identification number by its name. ER ercd = jti_get_tgr (char *tgrnm, JNO *p_tgrno) (2) [Parameters] char *tgrnm Java thread group name (ASCII character strings) JNO *p_tgrno Java thread group identification number (Pointer) (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_OBJ Specified Java thread group does not exist. E_PAR Wrong parameter (tgrnm is a NULL pointer) (5) [Remark] o Thread name should be within 31 characters in ASCII character strings. o Name the target Java thread always in Java program. 3.2.6.18 jti_des_tgr (1) [API] Calls the destroy method in the Java ThreadGroup class. ER ercd = jti_des_tgr (JNO tgrno) (2) [Parameters] JNO tgrno Java thread group identification number (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter E_OBJ A security exception or a status violation took place while executing the Java method. (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_tgr. 3.2.6.19 jti_sus_tgr (1) [API] Calls the suspend method in the Java ThreadGroup class. ER ercd = jti_sus_tgr (JNO tgrno) (2) [Parameters] JNO tgrno Java thread group identification number. (3) [Return value] ER ercd Error code (4) [Error codes] E_OK Normal termination E_PAR Wrong parameter (Illegal tgrno) E_OBJ A security exception took place while executing the Java method (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_tgr. 3.2.6.20 jti_rsm_tgr (1) [API] Calls the resume method in the Java ThreadGroup class ER ercd = jti_rsm_tgr (JNO tgrno) (2) [Parameters] JNO tgrno Java thread group identification number to be processed. (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_PAR Wrong parameter E_OBJ A security exception took place while executing the Java method. (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_tgr. 3.2.6.21 jti_stp_tgr (1) [API] Calls the stop method in the Java ThreadGroup class. ER ercd = jti_stp_tgr (JNO tgrno) (2) [Parameters] JNO tgrno Java thread group identi cation number (3) [Return value] ER ercd Error code (4) [Error code] E OK Normal termination E PAR Wrong parameter E OBJ A security exception took place while executing the Java method. (5) [Remark] The identification number of the target thread should be the value obtained by jti_get_tgr. ------------------------------------------------------------------------------ 3.3 Stream Class API Instructions ------------------------------------------------------------------------------ 3.3.1 General description By using this stream class, you can exchange data between an ITRON application and Java program via streams. A stream has two channels; sending channel to send data from an micro-ITRON realtime task to a Java thread and receiving channel where an micro-ITRON realtime task receives data from a Java thread. You can use both channels or use only one of the channels. InputStream and OutputStream, standard input/output interfaces of Java created in a stream class, are used when sending/receiving data on Java side. Below shows the relationship between channels and input/output interfaces. +----------------+ | Stream | | | +-----------+ +------+ |________________| +------+ |micro-ITRON|-|ITRON | -->> Sending channel -->> InputStream -->> |Java | |realtime | |API | |~~~~~~~~~~~~~~~~| |Thread| |task | | | |________________| | | | | | | <<-- Receiving channel <<-- OutputStream<<-- | | +-----------+ +------+ |~~~~~~~~~~~~~~~~| +------+ +----------------+ Figure 3.2 Channels and input/output interfaces o Java is a registered trademark of Sun Microsystems, Inc., of U.S.A. in U.S. A. and other countries. o A thread is an unit of process which always takes place when Java program is activated. o API (Application Programming Interface) is an interface between an operating system and an application program which operates in the OS. 3.3.2 Package name The classes for using streams from Java side are bundled together in the following package. jp.gr.itron.jtron.stream 3.3.3 General usage The summary of how this stream class is to be used is given below. 1. : Use an ITRON API to create a stream and connect the stream from an ITRON application task. 2. : Use a Java API and connect the stream from Java program. 3. : Use the ITRON API and Java API to execute read/write process for the stream from both of the ITRON application task and Java program to send/receive data. 4. : Use the ITRON API and Java API to disconnect the stream from both of the ITRON application program and Java program. 5. : Use the ITRON API to delete the stream. 3.3.4 Classes belonging to the package and ITRON API The classes to use stream from the Java side are shown below : (A)JtiDataStream (B)JtiDataStreamException The classes to use stream from the ITRON side are shown below : (A)jti_cre_stm (B)jti_del_stm (C)jti_wri_stm (D)jti_rea_stm (E)jti_sht_stm (F)jti_ref_stm 3.3.5 Stream class description 3.3.5.1 JtiDataStream (1) [Class (Super class)] public class JtiDataStream (2) [Description] The class to communicate with the micro-ITRON real-time task by using streams. (3) [Field] int MAIN STREAM // A standard stream identifier (4) [Constructor] (A)public JtiDataStream (int stmid) throws JtiDataStreamException, InterruptedException, IOException Opens the stream with the specified identifier. This sets both channels into the CONNECTED status. If the stream has only one channel, only that channel will be connected. If the specified identifier is already in use, a JtiDataStreamException will be thrown. (B)public JtiDataStream (int stmid,int tmout) throws java.io.IOException, java.lang.InterruptedException Opens the stream with the specified identifier and the additional timeout future. The unit of the timeout time is millisecond. If the specified identifier is already in use, a JtiDataStreamException will be thrown. When the timeout time has elapsed, an InterruptedException will be thrown. (C)protected JtiDataStream (JtiDataStreamImpl impl,int stmid,int tmout) throws java.io.IOException,java.lang.InterruptedException Opens the stream with the specified identifier with an additional timeout feature by using the user-defined implementation. The unit of the timeout time is millisecond. If the specified identifier is already in use, a JtiDataStreamException will be thrown. When the timeout time has elapsed, an InterruptedException will be thrown. (5) [Method] (D)public synchronized InputStream getInputStream () throws java.io.IOException Obtains the I/O stream for sending channel. (E)public synchronized OutputStream getOutputStream () throws java.io.IOException Obtains the I/0 stream for receiving channel. (F)public synchronized void setIDSTimeOut (int tmout) throws java.io.IOException Sets the timeout time for the case the read method for the InputStream is executed. The unit of the timeout time is millisecond and the timeout must be 0 or bigger. If 0 has been specified for the timeout, it will cause the permanent waiting. When the timeout time has elapsed, a java.io.InterruptedException will be thrown. However, if the write method was executed for the OutputStream, specifying the timeout will not be available just as the cases for the other stream operations. (G)public synchronized int getIDSTimeOut () throws java.io.IOException Obtains the timeout time for the case the read method for the InputStream is executed. The unit of timeout time is millisecond. Return of 0 means the permanent waiting. (H)public synchronized void close () throws java.io.IOException Closes the stream. If the sending channel has been connected, the method normally closes the stream to change the status to CLOSED status, and if the receiving channel has been connected, this method closes the stream by force to change the status to the FORCED DISCONNECTED status. This method also puts the status to the DISCONNECTED status if the receiving channel is in the CLOSED status (6) [Remark] No remark 3.3.5.2 JtiDataStreamException (1) [Class (Super class)] public class JtiDataStreamException extends java.io.IOException (2) [Description] Reports the occurrence of the exception related to the stream communication. (3) [Field] int Cause Cause identifer of the error. int STREAM_NOT_FOUND Specified stream does not exist. int STREAM_IN_USE Specified stream is already in use. int STREAM_CLOSED Specified stream is already closed. int STREAM_ILLEGAL_ARGUMENT Wrong parameter. (4) [Constructor] (A)public JtiDataStreamException (int c) Creates the JtiDataStreamException. Gives the cause identifier of the error to the parameter cause. (B)public JtiDataStreamException (int c,String msg) Creates the JtiDataStreamException with has the error message, msg. Gives the cause identifier of the error to the parameter cause. (5) [Method] (C)public int getCause () Returns the cause identifier of the error. (6) [Remark] No remark 3.3.6 Stream API description 3.3.6.1 jti_cre_stm (1) [API] ER ercd = jti_cre_stm(ID stmid,T_JTI_CSTM *pk_cstm) (2) [Parameters] stmid ID Stream identifier pk_cstm T_JTI_CSTM * Stream creation information Members of T_JTI_CSTM structure VP exinf Extension information ATR stmatr Stream attribute VP wbuf Head address of the sending buffer NADR means internal buffer. INT wbufsz Sending buffer size (byte) VP rbuf Head address of the receiving buffer NADR means internal buffer. INT rbufsz Receiving buffer size (byte) (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_ID Illegal ID number E_PAR Parameter error E_OBJ Object status error (5) [Remark] No remark 3.3.6.2 jti_del_stm (1) [API] Deletes streams ER ercd = jti_del_stm(ID stmid) (2) [Parameters] ID stmid Stream identifier (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_ID Illegal ID number E_NOEXS Object not created E_OBJ Object status error (5) [Remark] No remark 3.3.6.3 jti_wri_stm (1) [API] Sends data ER ercd = jti_wri_stm(ID stmid,VP data,INT len,TMO tmout) (2) [Parameters] ID stmid Stream identifier VP data Head address of the data to be sent INT len Length of the data to be sent TMO tmout Timeout time (3) [Return value] ER ercd Length of the data in the buffer or error code (4) [Error code] E_ID Illegal ID number E_NOEXS Object not created E_PAR Parameter error E_OBJ Object status error E_TMOUT Polling failure or timeout E_CLS The channel for sending was disconnected by force (5) [Remark] No remark 3.3.6.4 jti_rea_stm (1) [API] Receives data ER ercd = jti_rea_stm(ID stmid,VP data,INT len,TMO tmout) (2) [Parameters] ID stmid Stream identifier VP dat a Head address of the region to put the data received INT len Length of the data to be received TMO tmout Time-out specification (3) [Return value] ER ercd Length of the data received or error code (4) [Error code] E_ID Illegal ID number E_NOEXS Object not created E_PAR Parameter error E_OBJ Object status error E_TMOUT Polling failure or timeout (5) [Remark] No remark 3.3.6.5 jti_sht_stm (1) [API] Ends the data sending (2) [Parameters] ID stmid Stream identifier (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_ID Illegal ID number E_NOEXS Object not created E_OBJ Object status error E_CLS The channel for sending was disconnected by force (5) [Remark] No remark 3.3.6.6 jti_ref_stm (1) [API] Refers to the stream status ER ercd = jti_ref_stm(ID stmid,T_JTI_RSTM *pk_rstm) (2) [Parameters] ID stmid Stream identifier T_JTI_RSTM *pk_rstm Address of the packet to return the stream status Members of T_JTI_RSTM structure VP exinf Extension information INT wrisz Data size in bytes which can be send without waiting. INT reasz Data size in bytes which can be received without waiting. (3) [Return value] ER ercd Error code (4) [Error code] E_OK Normal termination E_ID Illegal ID number E_NOEXS Object not created E_PAR Parameter error (5) [Remark] No remark ============================================================================== 4. HOW TO USE CORBA-RELATED FUNCTION ============================================================================== ------------------------------------------------------------------------------ 4.1 CORBA-Related Function Interface Specification ------------------------------------------------------------------------------ Here describes the functional interface specification necessary for creating an application with CORBA-related function. An application with CORBA-related function can be realized by combining functions described in "4.1.1 Resource setting" and after. Refer to the sample program in the following directory for combination varieties of functions. +----------------------------------------------------------------------------+ |corbaapl/sample/long/src |A CORBA operation sample program with long-type | | |arguments and return codes | |---------------------------+------------------------------------------------| |corbaapl/sample/dync/src |Dynamic registration sample program | +----------------------------------------------------------------------------+ 4.1.1 Resource setting ------------------------------------------------------------------------------ [Function] embedded CORBA resource setting [Usage] CORBA_int ECORBA_init(SG_CORBA *corba_sg) [Parameters] SG_CORBA *corba_def /* Pointer to the request information of user-defined resource */ [Return parameters] CORBA_SGOK Normal termination CORBA_SGERR_SYS Resource setting failure in system-dependent section CORBA_SGERR_MRSHL Marshalling resource setting failure CORBA_SGERR_CON Connection management resource setting failure CORBA_SGERR_GIOP GIOP resource setting failure CORBA_SGERR_ORB ORB resource setting failure CORBA_SGERR_POA POA resource setting failure CORBA_SGERR_ASRV Auto startup resource setting failure [Description] The target machine which uses CORBA-related function needs to call this function once when initializing this feature. This function initializes embedded CORBA resource management function by obtaining upper limit resource size available for CORBA-related function and set value from arguments. The contents of SG_CORBA are describe below. typedef struct sg { CORBA_UsrDefine *sg_corba; ASRV_UsrDefine *sg_asrv; ORB_UsrDefine *sg_orb; POA_UsrDefine *sg_poa; MRSHL_UsrDefine *sg_mrshl; GIOP_UsrDefine *sg_giop; CON_UsrDefine *sg_con; SYS_UsrDefine *sg_sys; void *sg_rfu1; void *sg_rfu2; void *sg_rfu3; void *sg_rfu4; } SG_CORBA; The members of SG_CORBA are shown below; (1) CORBA_UsrDefine-type data typedef struct corba_init { CORBA_char *corba_tgtnam; CORBA_unsigned_long corba_srvnum; CORBA_unsigned_long corba_memsz; CORBA_char *corba_buffp; void *corba_rfu1; void *corba_rfu2; void *corba_rfu3; void *corba_rfu4; } CORBA_UsrDefine; o corba_tgtnam Pointer to target name o corba_srvnum The number of server tasks which use the CORBA-related function in the target machine. There are three ways of starting a server task with CORBA-related function as shown below. (a) Server created/started immediately after initialization. (b) Server registered as auto start server immediately after initialization and started upon receiving a request. (c) Server registered as auto start server during operation and started upon receiving a request. The relationship shown below is always true among asrv_dservnm and asrv_ddobjnm, the members of ASRV_UsrDefine structure and this member. Refer to "(2) ASRV_UsrDefine-type data" described later for ASRV_UsrDefine structure. corba_srvnm = (asrv_dservnm + asrv_ddobjnm) Therefore, above (A), (B) and (C) have the relationship given below. (A)+(B)+(C)= corba_srvnm (A)= corba_srvnm - asrv_dservnm - asrv_ddobjnm (B)= asrv_dservnm (C)= asrv_ddobjnm o corba_memsz Total memory area size available for CORBA-related function. o corba_buffp Fixed to 0. o corba_rfu1, corba_rfu2, corba_rfu3 and corba_rfu4 Reserved area (2) ASRV_UsrDefine-type data typedef struct asrv_usrdef { ID asrv_aservid; PRI asrv_asrvpri; PRI asrv_dsrvpri; CORBA_unsigned_short asrv_portnum; CORBA_unsigned_long asrv_dservnm; CORBA_unsigned_long asrv_ddobjnm; void *asrv_rfu1; void *asrv_rfu2; void *asrv_rfu3; void *asrv_rfu4; } ASRV_UsrDefine; o asrv_aservid Task ID for auto start server o asrv_asrvpri Priority of auto start server o asrv_dsrvpri Initial priority for the server task automatically started. A priority higher than the priority of auto start server must be specified. The server task started by auto start server is executed with a priority higher than that of auto start server when being created/started. As soon as the task is ready for receiving data, it runs with the priority originally specified by an user. o asrv_portnum Port No for auto start server. o asrv_dservnm The number of server tasks automatically started. o asrv_ddobjnm The number of server tasks dynamically registered in auto start server while the target system is running and then automatically started o asrv_rfu1, asrv_rfu2, asrv_rfu3 and asrv_rfu4 Reserved area (3) ORB_UsrDefine-type data Fixed to 0 since no resource requires setting. (4) POA_UsrDefine-type data typedef struct tagPOA_UsrDefine { CORBA_unsigned_long poa_limit; CORBA_unsigned_long map_limit; void *poa_rfu1; void *poa_rfu2; void *poa_rfu3; void *poa_rfu4; } POA_UsrDefine; o poa_limit Upper limit for object adapter available for CORBA-related function o map_limit Upper limit for servant available for CORBA-related function o poa_rfu1, poa_rfu2, poa_rfu3 and poa_rfu4 Reserved area (5) MRSHL_UsrDefine-type data Fixed to 0 since no resource requires setting. (6) GIOP_UsrDefine-type data Fixed to 0 since no resource requires setting. (7) CON_UsrDefine-type data typedef struct con_usr_define { CORBA_unsigned_long con_srvlim; CORBA_unsigned_long con_clilim; CORBA_unsigned_long con_tmout; void *con_rfu1; void *con_rfu2; void *con_rfu3; void *con_rfu4; } CON_UsrDefine; o con_srvlim Upper limit for connection management per server task The total number of connections available for server objects is the result of multiplying the value set by this member by the value set by corba_srvnum, the member of CORBA_UsrDefine-type data. o con_clilim Upper limit for connection management for client The value set by this member gives the total number of connections available for client. o con_tmout Interval to check the termination of a server task (in microseconds) o con_rfu1, con_rfu2, con_rfu3 and con_rfu4 Reserved area (8) SYS_UsrDefine-type data Fixed to 0 since no resource requires setting. 4.1.2 ORB ------------------------------------------------------------------------------ [Function] Initializing ORB [Usage] CORBA_ORB CORBA_ORB_init(int *argc, char **argv, CORBA_ORBid orb_identifier, CORBA_Environment *env); [Parameters] int *argc /* Pointer to the number of configuration information */ char **argv /* Pointer to the head address of configuration information storage area */ CORBA_ORBid orb_identifier /* ORB identifier */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Normal termination ORB object Abnormal termination NULL Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function obtains an ORB object. By specifying a character string "e-corba" in the argument orb_identifier and calling this function, an application initializes CORBA-related function. Set 1 to the argument *argc of this function for the server task which is expected to be started by auto start server (server task which has permanent POA). Then, the pointer to the first address of the area where a character string "ServerName=" is stored needs to be set in the argument **argv. Specify the name of the server task to this . Specify 0 to the argument *argc for tasks with no name. The ORB object which becomes return code uses the memory area obtained within this function. Therefore, the memory area must be freed by a function "CORBA_Object_release" when the ORB object is no more necessary. ------------------------------------------------------------------------------ [Function] Obtaining initial object [Usage] CORBA_Object CORBA_ORB_resolve_initial_references(CORBA_ORB orb, CORBA_char *object_name, CORBA_Environment *env) [Parameters] CORBA_ORB orb /* ORB object */ CORBA_char *object_name /* Pointer to the name of the initial object you would like to get.*/ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Normal termination CORBA object Abnormal termination NULL Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function obtains the CORBA object of the service specified by the argument "object_name". By specifying a character string "RootPOA" in the argument "*object_name", an application in the server initialize POA and obtains CORBA-object-type RootPOA. Specify the ORB object obtained by a function "CORBA_ORB_init" to the argument "orb" of this function. The CORBA object which becomes return code uses the memory area obtained within this function. Therefore, the memory area must be freed by a function "CORBA_Object_release" when the CORBA object is no more necessary. ------------------------------------------------------------------------------ [Function] Converting CORBA object into character string [Usage] CORBA_char * CORBA_ORB_object_to_string(CORBA_ORB orb, CORBA_Object obj, CORBA_Environment *env) [Parameters] CORBA_ORB orb /* ORB object */ CORBA_Object obj /* CORBA object */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Normal termination Character strings (IOR format) Abnormal termination NULL Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function converts the CORBA object specified by the argument "obj" into a character string in IOR format which takes interoperability into account. Specify the ORB object obtained by a function "CORBA_ORB_init " to the argument "orb" of this function. The IOR which becomes return code uses the memory area obtained within this function. Therefore, the memory area must be freed by a function "CORBA_free" when the IOR is no more necessary. ------------------------------------------------------------------------------ [Function] Converting character string into CORBA object [Usage] CORBA_Object CORBA_ORB_string_to_object(CORBA_ORB orb, CORBA_char *buf, CORBA_Environment *env) [Parameters] CORBA_ORB orb /* ORB object */ CORBA_char *buf /* Pointer to the charater strings */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameter] Normal termination CORBA object Abnormal termination NULL Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function converts the character string (in IOR format) specified by the argument *buf into a CORBA object. A client application uses the CORBA object obtained by this function to call an operation. Specify the ORB object obtained by a function "CORBA_ORB_init " to the argument "orb" of this function. The CORBA object which becomes return code uses the memory area obtained within this function. Therefore, the memory area must be freed by a function "CORBA_Object_free" when the CORBA object is no more necessary. ------------------------------------------------------------------------------ [Function] Waiting to receive request [Usage] void CORBA_ORB_run(CORBA_ORB orb, CORBA_Environment *env) [Parameters] CORBA_ORB orb /* ORB object */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] A server object calls this function and enters a loop to wait to receive a request from client. Specify the ORB object obtained by a function "CORBA_ORB_init" to the argument "orb" of this function. If a request from client is received, this function calls an appropriate servant. ------------------------------------------------------------------------------ [Function] Server termination setting [Usage] void CORBA_ORB_shutdown(CORBA_ORB orb, CORBA_Environment *env) [Parameters] CORBA_ORB orb /* ORB object */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] When a server application calls a function "CORBA_ORB_run" and starts waiting for receiving an request, the function "CORBA_ORB_run" does not return. However, if this function was called within a servant function registered in server application, the function "CORBA_ORB_run" is capable of returning. 4.1.3 CORBA Object ------------------------------------------------------------------------------ [Function] Releasing CORBA object [Usage] void CORBA_Object_release(CORBA_Object obj, CORBA_Environment *env) [Parameters] CORBA_Object obj /* CORBA object */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter. Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function releases the CORBA object specified by the argument "obj". 4.1.4 POA ------------------------------------------------------------------------------ [Function] Creating POA [Usage] void PortableServer_POA_create_POA(PortableServer_POA poa, CORBA_char *adapter_name, PortableServer_POAManager mgr, CORBA_PolicyList *policies, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* Parent POA of POA to be created */ CORBA_char *adapter_name /* Name of POA to be created */ PortableServer_POAManager mgr /* POAManager of POA to be created (NULL creates POAManager) */ CORBA_PolicyList *policies /* Policy list of POA to be created */ CORBA_Environment *env /* Pointer to the environment variables */ [Description] This function creates a POA. This functional interface is used to create a child POA for the parent POA already created by a function "CORBA_ORB_resolve_initial_references". If the argument "adapter_name" is the same with a POA already registered, that POA is not registered and an exception is set to the argument *env. If the argument "mgr" is NULL, POAManager is created to manage argument "poa". Use the function "PortableServer_POA__get_the_POAManager" described later to obtain and use the POAManager created. In addition, if "mgr" is the POAManager of a POA created before, a POA is set in the management list of the POAManager. Set NULL to the argument "poliese" when no policy is to be set and set the policy list with LifespanPolicy set when creating a POA which is to be a permanent policy. ------------------------------------------------------------------------------ [Function] Deleting POA [Usage] void PortableServer_POA_destroy(PortableServer_POA poa, CORBA_boolean etherealize_objects, CORBA_boolean wait_for_completion, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* POA to be deleted */ CORBA_boolean etherealize_objects /* Flag : Whether the servant manager keep the object condition or not */ CORBA_boolean wait_for_completion /* Flag : Whether it waits the invocation of all request or not */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function deletes a POA. An argument "etherealize_objects" is ignored since the CORBA-related function does not support servant manager. Moreover, an argument "wait_for_completion" is also ignored for CORBA-related function. This function deletes the POA created by a function "CORBA_ORB_resolve_initial_references" and a function "PortableServer_POA_create_POA". When a POA created by a function "CORBA_ORB_resolve_initial_references" or a function "PortableServer_POA_create_POA" is no more necessary, it has to be deleted by using this function. ------------------------------------------------------------------------------ [Function] Obtaining POA name [Usage] CORBA_char * PortableServer_POA__get_the_name(PortableServer_POA poa, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* POA whose name to be obtained */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] POA name given by the argument "poa" Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function obtains a POA name. Here, the POA name set to the argument "*adapter_name" of the function "PortableServer_POA_create_POA" is returned. In case of RootPOA created by a function "CORBA_ORB_resolve_initial_references", "RootPOA" returns. ------------------------------------------------------------------------------ [Function] Obtaining parent POA [Usage] POA PortableServer_POA__get_the_parent(PortableServer_POA poa, CORBA_environment *env) [Parameters] PortableServer_POA poa /* POA from which its parent POA is got */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] The parent POA of the POA given by the argument "poa" Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function obtains the parent POA of the POA given by the argument "poa". The parent POA set by the argument "poa" of a function "PortableServer_POA_create_POA" returns. In case of RootPOA created by a function "CORBA_ORB_resolve_initial_references, a NULL returns since no parent POA exists for the POA. ------------------------------------------------------------------------------ [Function] Obtaining POAManager [Usage] POA PortableServer_POA__get_the_POAManager(PortableServer_POA poa, CORBA_environment *env) [Parameters] PortableServer_POA poa /* POA controlled by POAManager */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] POAManager for the POA given by the argument "poa" Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function returns the POAManager which manages the POA specified by the argument "poa". The POAManager set to the argument "mgr" of the function "PortableServer_POA_create_POA" returns. If the argument "mgr" of the function "PortableServer_POA_create_POA" has been set to NULL, the POAManager created by a function "PortableServer_POA_create_POA" returns. In case of RootPOA created by a function "CORBA_ORB_resolve_initial_references", the POAManager created by a function "CORBA_ORB_resolve_initial_references" returns. ------------------------------------------------------------------------------ [Function] Creating a POA permanent policy [Usage] LifespanPolicy create_lifespan_policy(PortableServer_POA poa, LifespanPolicyValue value, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* POA which sets the policy */ LifespanPolicyValue value /* The value of lifespan policy */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Set permanent policy Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function creates a POA permanent policy. There are two types of POA permanent policies; volatile POA and permanent POA. A servant created by volatile POA cannot be re-created once the application task is terminated. A servant created by permanent POA is permanent regardless of the life span of the application task. The permanent policies which can be set are given below. PortableServer_TRANSIENT /* Volatile POA */ PortableServer_PERSISTENT /* Permanent POA */ ------------------------------------------------------------------------------ [Function] Registering servant to POA [Usage] void PortableServer_POA_activate_object_with_id(PortableServer_POA poa, PortableServer_ObjectId oid, PortableServer_Servantp_servant, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* POA to which the servant is registered. */ PortableServer_ObjectId oid /* Object identifier of the new object */ PortableServer_Servant p_servant /* Servant to be registered */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter. Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function registers a servant to POA with the object ID (argument "oid") as an identifier. With this function, a server program registers an implemented object (servant) to POA. The registered servant is identified by the object ID specified by the argument "oid". The servant registered by this function is managed by a table which pairs a servant with its object ID. This memory area is maintained by POA until the servant is deleted. Therefore, the registered servant needs to be deleted with a function "PortableServer_POA_deactivate_object_with_id" when the servant is no more necessary. ------------------------------------------------------------------------------ [Function] Deleting servant from POA [Usage] void PortableServer_POA_deactivate_object_with_id(PortableServer_POA poa, PortableServer_ObjectId oid, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* POA which controls servants */ PortableServer_ObjectId oid /* Object identifier of the object to be deleted */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter. Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function deletes a servant registered to POA. For deletion, this function searches for the object ID specified by the argument "oid" and deletes the servant which has the corresponding object ID. Note that this object ID is the one used for registering the servant. ------------------------------------------------------------------------------ [Function] Obtaining CORBA object from servant [Usage] PortableServer_Object PortableServer_POA_servant_to_reference(PortableServer_POA poa, PortableServer_Servant p_servant, CORBA_Environment *env) [Parameters] PortableServer_POA poa /* POA which controls servants */ PortableServer_Servant p_servant /* Servant which CORBA objects are obtaind from */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameter] CORBA object corresponding with the argument "p_servant" Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function obtains a CORBA object from a servant. This function searches for the object ID in POA active object map by using the servant as a key. Then this function creates a CORBA object using the object ID matched in search to be the return code. This function obtains the memory area for the CORBA object. Therefore, the memory area must be freed by a function "CORBA_Object_release" when the CORBA object is no more necessary. ------------------------------------------------------------------------------ [Function] Activating POAManager [Usage] void PortableServer_POAManager_activate(PortableServer_POAManager mgr, CORBA_Environment *env) [Parameters] PortableServer_POAmanager mgr /* POAManager to be activated */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter. Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function activates POAManager. It activates the POA which belongs to the POAManager specified by the argument "mgr" so that the POA becomes ready to receive messages. 4.1.5 exception ------------------------------------------------------------------------------ [Function] Initializaing environment variables [Usage] void CORBA_exception_init(CORBA_Environment *env) [Parameters] CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] No parameter [Description] This function initializes environment variables. This function must be called in an application before using the environment variable. ------------------------------------------------------------------------------ [Function] Setting exception information to environmental variables [Usage] void CORBA_exception_set(CORBA_Environment *env, CORBA_exception_type major, CORBA_char *exception_repos_id, void *param); [Parameters] CORBA_Environment *env /* Pointer to the environment variables */ CORBA_exception_type major /* Major number */ CORBA_char *exception_repos_id /* Pointer to the exception identifier */ void *param /* Pointer to the additional exception information */ [Return parameters] No parameter [Description] This function sets the argument "major", "*exception_repos_id" and "*param" in the argument "*env". The following values can be set to the argument "major". CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred The values which can be set to the argument "*exception_repos_id" are character strings which specify an exception type. Specify a character string which indicates the type for system exception specified in CORBA specification if CORBA_SYSTEM_EXCEPTION is specified in the argument "major". Specify a character string which indicates the type for user-defined exception if CORBA_USER_EXCEPTION is specified in the argument "major". If there is any additional exception information, set a pointer to the information in the argument "*param". Otherwise, set 0. This function obtains memory area when setting exception information in the argument "*env". Therefore, the obtained memory area must be freed by a function "CORBA_exception_free" when the exception information is no more necessary. ------------------------------------------------------------------------------ [Function] Obtaining exception identifier [Usage] CORBA_char * CORBA_exception_id(CORBA_Environment *env); [Parameters] CORBA_Environment *env /* Pointer to the environment variable */ [Return parameters] Pointer to the character strings of exception identifier [Description] Pointer to the character string which is an exception identifier This function sets the pointer to the exception identifier set in the argument "*env" as the return code. If "_major", a member of the argument "*env" which is the pointer to CORBA_Environment-type data, is CORBA_USER_EXCEPTION or CORBA_SYSTEM_EXCEPTION, the exception identifier which gives exception type information can be obtained by calling this function. ------------------------------------------------------------------------------ [Function] Obtaining additional exception information [Usage] void * CORBA_exception_value(CORBA_Environment *env); [Parameters] CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Pointer to the additional exception information [Description] Pointer to the additional exception information. This function sets the pointer to the additional exception information set in the argument "*env" as the return code. If "_major", a member of the argument "*env" which is the pointer to CORBA_Environment-type data, is CORBA_USER_EXCEPTION or CORBA_SYSTEM_EXCEPTION, the additional exception information can be obtained by calling this function. ------------------------------------------------------------------------------ [Function] Releasing memory area for exception information [Usage] void CORBA_exception_free(CORBA_Environment *env); [Parameters] CORBA_Environment *env /* Pointer to the environment variables */ [Return parameter] No parameter [Description] This function frees the memory area where the exception information set in the argument "*env" is stored. 4.1.6 memory [Function] Obtaining memory [Usage] void * CORBA_malloc(CORBA_unsigned_long size, CORBA_unsigned_long count, f_func func) [Parameters] CORBA_unsigned_long size /* Size of memory */ CORBA_unsigned_long len /* Number of Obtained memory */ f_func func /* Pointer to the function to free memory area */ [Return parameters] The first address of the memory to be obtained [Description] This function obtains the memory area of necessary size (argument "size" * argument "len"). At this point, the area to store the obtained memory area (32 bytes) is also consumed. The memory area obtained by this function must be freed by a function "CORBA_free". When the obtained memory is used as an array and individual element of the array has further pointer to dynamically obtained memory, and if a function to free the dynamically obtained memory is available, a pointer to the memory release function can be set in the argument "func". Furthermore, this function sets the number of elements in the array in the argument "count". The arguments "count" and "func" are used when a function "CORBA_free" is called. ------------------------------------------------------------------------------ [Function] Releasing memory [Usage] void CORBA_free(void *bufp) [Parameters] void *bufp /* Pointer to the memory area to be freed */ [Return parameters] No parameter [Description] This function frees the memory area specified by the argument "bufp". If a memory release function for the area specified by the argument "bufp" has been set, this function calls the memory release function to free the memory. 4.1.7 stub skeleton ------------------------------------------------------------------------------ [Function] Function to obtain index in sending buffer [Usage] CORBA_unsigned_long MRSHL_index_octet(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_boolean(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_char(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_short(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_unsigned_short(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_long(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_unsigned_long(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_long_long(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_unsigned_long_long(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_float(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_double(CORBA_unsigned_long index) CORBA_unsigned_long MRSHL_index_string(CORBA_unsigned_long index, CORBA_char *str) [Parameters] CORBA_unsigned_long index /* The index in the sending buffer at the start of marshalling */ CORBA_char *str /* Pointer to the character strings. Only the function MRSHL_index_string requires them. */ [Return parameters] The index in the sending buffer after marshalling [Description] Index in sending buffer after marshalling [Description] Index in sending buffer is an offset value from the head of the sending buffer after marshalling. The index value for the head of the sending buffer is 0. This function only demands index without marshalling. You need to use different function given in the [Usage] (shown above) according to the type of data to be marshalled. The index value after storing CORBA_octet-type data is given by the argument "index", current index value in buffer. The index value given is the memory size required for marshalling. In addition, an argument "str" (pointer to character string) is required only when asking index in sending buffer after marshalling character-string-type data. The index in buffer (memory size required for mashalling) is given as follows when CORBA operation uses two arguments of long-type data and short-type data. CORBA_unsigned_long index; index = 0; index = MRSHL_index_long(index); index = MRSHL_index_short(index); ------------------------------------------------------------------------------ [Function] Marshalling function [Usage] void MRSHL_put_octet(CORBA_char **bufp, CORBA_octet data) void MRSHL_put_boolean(CORBA_char **bufp, CORBA_boolean data) void MRSHL_put_char(CORBA_char **bufp, CORBA_char data) void MRSHL_put_short(CORBA_char **bufp, CORBA_short data) void MRSHL_put_unsigned_short(CORBA_char **bufp, CORBA_unsigned_short data) void MRSHL_put_long(CORBA_char **bufp, CORBA_long data) void MRSHL_put_unsigned_long(CORBA_char **bufp, CORBA_unsigned_long data) void MRSHL_put_long_long(CORBA_char **bufp, CORBA_long_long data) void MRSHL_put_unsigned_long_long(CORBA_char **bufp, CORBA_unsigned_long_long data) void MRSHL_put_float(CORBA_char **bufp, CORBA_float data) void MRSHL_put_double(CORBA_char **bufp, CORBA_double data) void MRSHL_put_string(CORBA_char **bufp, CORBA_char *data) [Parameters] CORBA_char **bufp /* Pointer to the strage area of sending buffer address */ Target data type of marshalling data /* The type of data to be marshalled or pointer to the character strings when they are marshalled */ [Return parameters] No parameter [Description] You have to use different function given in the [Usage] (shown above) according to the type of data to be marshalled. The address in the sending buffer after storing data is the addition of index value obtained by "Function to obtain index in sending buffer" to the argument "**bufp". The marshalling to the sending buffer is done as follows when CORBA operation uses two arguments of long-type data and short-type data. CORBA_long ldata; CORBA_short sdata; CORBA_char *bufp; MRSHL_put_long(&bufp, ldata); MRSHL_put_short(&bufp, sdata); ------------------------------------------------------------------------------ [Function] Unmarshalling function [Usage] CORBA_octet MRSHL_get_octet(CORBA_char **bufp) CORBA_boolean MRSHL_get_boolean(CORBA_char **bufp, CORBA_boolean order) CORBA_char MRSHL_get_char(CORBA_char **bufp, CORBA_boolean order) CORBA_short MRSHL_get_short(CORBA_char **bufp, CORBA_boolean order) CORBA_unsigned_short MRSHL_get_unsigned_short(CORBA_char **bufp, CORBA_boolean order) CORBA_long MRSHL_get_long(CORBA_char **bufp, CORBA_boolean order) CORBA_unsigned_long MRSHL_get_unsigned_long(CORBA_char **bufp, CORBA_boolean order) CORBA_long_long MRSHL_get_long_long(CORBA_char **bufp, CORBA_boolean order) CORBA_unsigned_long_long MRSHL_get_unsigned_long_long(CORBA_char **bufp, CORBA_boolean order) CORBA_float MRSHL_get_float(CORBA_char **bufp, CORBA_boolean order) CORBA_double MRSHL_get_double(CORBA_char **bufp, CORBA_boolean order) CORBA_char * MRSHL_get_string(CORBA_char **bufp, CORBA_boolean order) [Parameters] CORBA_char **bufp /* Pointer to the strage area of receiving buffer address */ CORBA_boolean order /* Byte order of data in receiving buffer */ CORBA_TRUE : Little endian CORBA_FALSE: Big endian */ [Return parameter] Data after unmershalling. This will be a pointer to a character string if the data is a character string. [Description] You have to use different function given in the [Usage] (shown above) according to the type of data to be unmarshalled. This function takes out data stored in the area specified by the argument "**bufp" and sets the data as the return code. If the argument "order" is different from a native byte order at this point, the value converted into native byte order is set as the return code. The address in the buffer after taking out data is the addition of the index value obtained by "Function to obtain index in sending buffer" to the argument "**bufp". If the data to be unmarshalled is a character string, this function obtains memory area to store the character string and stores the character string in the area. Then, the first address of the area is set as the return code. Should this function fail to obtain memory area, 0 will be set as the return code. The obtained memory area can be freed by a function "CORBA_free". The data is to be taken out of the receiving buffer as follows when CORBA operation uses two arguments of long-type data and short-type data. CORBA_long ldata; CORBA_short sdata; CORBA_char *bufp; CORBA_boolean order; ldata = MRSHL_get_long(&bufp, order); sdata = MRSHL_get_short(&bufp, order); ------------------------------------------------------------------------------ [Function] Initializing sending/receiving on client side [Usage] void GIOP_init_cli(GIOP_CliInf *inf) [Parameters] GIOP_CliInf *inf /* Pointer to the GIOP management data on client side */ [Return parameters] No parameter [Description] This function sets an initial value to the information indicated by the argument "*inf". This function must be called in the first process in a stub function. ------------------------------------------------------------------------------ [Function] Terminating sending/receiving on client side [Usage] void GIOP_end_cli(GIOP_CliInf *inf) [Parameters] GIOP_CliInf *inf /* Pointer to the GIOP management data on client side */ [Usage] This function executes termination process for the information indicated by the argument "*inf". To be more specific, this function frees the memory used for sending/receiving data. This function must be called when returning from a stub function. ------------------------------------------------------------------------------ [Function] Creating sending buffer for request [Usage] CORBA_char * GIOP_create_reqbuf(CORBA_Object obj, GIOP_CliInf *inf, CORBA_unsigned_long dsize, CORBA_boolean akflg, CORBA_char *op, CORBA_Environment *env) [Parameters] CORBA_Object obj /* CORBA object */ GIOP_CliInf *inf /* Pointer to the GIOP management data on client side */ CORBA_unsigned_long dsize /* Size of operation parameters */ CORBA_boolean akflg /* Flag : whether it waits reply or not. Fixed to CORBA_TRUE */ CORBA_char *op /* Pointer to the operation name */ CORBA_Environment *env /* Pointer to the environment variables */ [Description] Normal termination Address in the sending buffer Abnormal termination NULL Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] Only the sending buffer of the memory size which totaled the request header size and operation argument size (argument "dsize") is to be obtained. This function stores the request header including reply-waiting flag (argument "akflg") and operation name (argument "*op") in the obtained sending buffer. The bottom address of the request header area in the sending buffer is set as the return code of this function. This means that the data which is to be an argument of the operation in stub is stored in the address of the return code of this function by using marshalling function from the first address. ------------------------------------------------------------------------------ [Function] Sending/Receiving request [Usage] CORBA_char * GIOP_invoke_req(CORBA_Object obj, GIOP_CliInf *inf, CORBA_unsigned_long size, CORBA_Environment *env) [Parameters] CORBA_Object obj /* CORBA object */ GIOP_CliInf *inf /* Pointer to the GIOP management data on client side */ CORBA_unsigned_long size /* Size of sending buffer */ CORBA_Environment *env /* Pointer to the environment variables */ [Return parameters] Normal termination Address in the receiving buffer Abnormal termination NULL Whether the process was terminated normally or abnormally is judged by referring to _major, a member of CORBA_Environment-type data, set in the argument *env of this function after calling this function. The values the member _major may obtain are listed below. CORBA_NO_EXCEPTION No exception occurred CORBA_USER_EXCEPTION User-defined exception occurred CORBA_SYSTEM_EXCEPTION System exception occurred [Description] This function sends a request to the server and receives the reply. The data of the byte size indicated by the argument "size" (data in the buffer managed by the argument "*inf") is sent to the server. Then this function obtains the receiving buffer area when receiving the reply to store the data received. The pointer to the receiving buffer is set as the return code of this function. This means that the data which is to be the return code of the operation in stub is stored in the address, which is the return code of this function, by using unmarshalling function from the first address. ------------------------------------------------------------------------------ [Function] Creating sending buffer for reply [Usage] CORBA_char * GIOP_create_repbuf(GIOP_SrvInf *inf, CORBA_unsigned_long dsize) [Parameters] GIOP_SrvInf *inf /* Pointer to the GIOP management data on server side */ CORBA_unsigned_long dsize /* Size of return parameters by the operation */ [Return parameters] Normal termination Address in sending buffer Abnormal termination 0 [Description] Only the sending buffer of the memory size which totaled the reply header size and operation return code size (argument "dsize") is to be obtained. The server side GIOP management data (argument "*inf") manages the sending buffer. This function stores the reply header in the obtained sending buffer. The bottom address of the reply header area in the sending buffer is set as the return code of this function. This means that the data which is to be the return code of the operation in skeleton is stored in the address, which is the return code of this function, by using marshalling function from the first address. ------------------------------------------------------------------------------ [Function] Sending reply [Usage] void GIOP_send_rep(GIOP_SrvInf *inf, CORBA_unsigned_long size) [Parameters] GIOP_SrvInf *inf /* Pointer to the GIOP management data on server side */ CORBA_unsigned_long size /* Size of sending buffer */ [Return parameters] No parameter [Description] This function sends a reply. The data of the byte size indicated by the argument "size" in the buffer the argument "*inf" manages is sent to the client. ------------------------------------------------------------------------------ [Function] Sending system exception reply [Usage] GIOP_send_repexc(GIOP_SrvInf *inf, CORBA_char *id, CORBA_unsigned_long completed) [Parameters] GIOP_SrvInf *inf CORBA_char *id /* Exception Identifier (Pointer to the character strings)*/ CORBA_unsigned_long completed /* Flag : Whether the operation is called or not. CORBA_COMPLETED_YES The operation has been called. CORBA_COMPLETED_NO The operation has not been called. CORBA_COMPLETED_MAYBE The operation may have been called. */ [Return parameters] No parameter [Description] This function is called by a skeleton. This function is used to notify the client of system exception occurrence when a system exception is issued during processing operation or in skeleton. The argument "*id" specifies the type of system exception and the argument "completed" specifies whether to call the operation or not. This function sends the specified information to the client as system exception information. 4.1.8 Dynamic entry ------------------------------------------------------------------------------ [Function] Registering dynamic object [Usage] CORBA_int ASRV_entry_dobj(T_CTSK *tskinf, CORBA_char *srvnm, CORBA_int vers) [Parameters] T_CTSK *tskinf /* Pointer to the server task creation information */ CORBA_char *srvnm /* Pointer to the server name */ CORBA_int vers /* Version number */ [Return parameter] Normal termination Dynamic object identifier (Positive Integer) Abnormal termination Negative Integer [Description] This function registers a server task which behaves as a server object in the already running system with CORBA-related function. Server task creation information (argument "*tskinf"), server name (argument "*srvnm") and version number (argument "vers") of the server task CORBA-related function manages should be specified in the arguments of this function. When the server task was registered normally, a dynamic object identifier (positive integer) which uniquely identifies the server will return as the return code. If another server has been already registered under the same server name or if the memory area required for registering the server task cannot be obtained, the registration process is not to be executed and a negative integer will return as the return code. The server registered by this function is started for the first time when a request from client is received. Therefore, client needs to have an IOR which contains server location information ready before the server starts. This IOR can be obtained by using cre_ior, an IOR creation command. In addition, the objects registered by this function must be implemented as permanent objects. ------------------------------------------------------------------------------ [Function] Deleting dynamic object [Usage] ID ASRV_cancel_dobj_id(CORBA_int doid) [Parameters] CORBA_int doid /* Dynamic object identifier */ [Return parameter] Server task identifier to be deleted. [Description] This function stops the service of the server task registered by the function "ASRV_entry_dobj" and deletes the server task. The dynamic object identifier of the server task to be deleted should be specified in the argument "doid" of this function. This function performs deletion process and sets the task ID of the server task to be deleted as the return code and returns to where the system call was called. If the server task to be deleted is processing a request from client at the point this function was called, the server task will be deleted as soon as the process is completed. Therefore, the server task may be still operating and have not been deleted yet when this function returned. ------------------------------------------------------------------------------ 4.2 IOR Creation Command ------------------------------------------------------------------------------ An IOR which contains location information of the server object (server task) dynamically registered in a running system by using CORBA-related function is to be created by a command "cre_ior". Note that this command cannot create the IOR of the server object (server task) statically created in initializing the system. [Usage] cre_ior [Parameters] Server machine host name Auto start server port number working in server machine Server name of the registered object (server task) Servant IDL definition Hierarchy information for POA where the servant is located Servant object ID [Description] This command sets the same setting contents with the setting contents of the server object (server task) dynamically registered in a running system by using CORBA-related function in parameters of this command. By calling the function "CORBA_ORB_string_to_object" with the IOR obtained by this command as its argument, the CORBA object of the dynamically registered server object can be obtained. Then a client application will be able to send a request by using the CORBA object obtained. [Example] cre_ior rtpgw5 5000 test-srv IDL:TestModule/TestIF RootPOA/test_poatest_object ============================================================================== 5. HOW TO USE GUI MIDDLEWARE FUNCTION ============================================================================== "GUI middleware function" consists of the following 5 functions; "Event management function", "Panel management function", "Parts management function", "Character input management function" and "Data box management function". The outline and API (Application Program Interface) for the system calls of each function are described below. Since the panel management function covers a wide range of items, this function is divided into drawing section and scene/panel section. "GUI middleware function" is provided as a library. This library works as an execution program by being linked with an application program developed by an user and can be executed by being downloaded into the target machine. Also refer to "Appendix 1 GUI middleware function external specifications" or details of parameters, etc. ------------------------------------------------------------------------------ 5.1 GUI Middleware Function Outline ------------------------------------------------------------------------------ 5.1.1 Event management function An event is given in the following structure. typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; "type" indicates an event type. "pos" indicates current PD position and "key" indicates the character code corresponding to the key for a key event. "stat" stores the time of event occurrence in upper 16 bits. The following values can be set as "type". #define GE_NULL 0 #define GE_BUTDWN 1 #define GE_BUTUP 2 #define GE_KEYDWN 3 #define GE_KEYUP 4 #define GE_AUTKEY 5 "GE_NULL" indicates a NULL event which occurs when PD moved, etc. "GE_BUTDWN" is issued when the button was pressed and "GE_BUTUP" when the button was released. These events store the PD coordinates in "pos" and the event occurrence time in "stat". The value of "key" has no meaning. "GE_KEYDWN" is issued when a character key was pressed and "GE_KEYUP" when the character key was released. "GE_AUTKEY" is a key repeat event and issued continuously when a character key was kept pressed. These events store the PD coordinates in "pos", the character code corresponding to the key in "key" and the event occurrence time in "stat". 5.1.2 Panel management function - Drawing section The panel management function provides a virtualized screen as a drawing environment so that the screen can be shared by several tasks. Because a part of the screen is allocated to a drawing environment so that it will not overlap other drawing environments, you will not affect other tasks when drawing in a drawing environment from several tasks. The coordinates have the upper left of the screen as {0, 0} and the ordinate (X-coordinate) increases to the right and the abscissa (Y-coordinate) increases downward. An ID is assigned to a drawing environment and a drawing environment ID is obtained when the drawing environment is created. Use this ID to access the drawing environment. Drawing offset, visible rectangle, prefix rectangle array and current font are set in a drawing environment. A drawing offset is drawn by being added to the coordinates given as a drawing request and can change the drawing position while the coordination specification remains unchanged. A visible rectangle is a function not to allow drawing outside this rectangle area. A prefix rectangle array is a function not to allow drawing inside the rectangle area specified in this array. At the point a drawing environment is created, the drawing offset is set to {0, 0}, visible rectangle set to entire screen and prefix rectangle array set to null. In general usage of GUI middleware, the upper left coordinates of the panel is set as drawing offset, outer frame of the panel as visible rectangle and outer frame coordinates of the panel located in front as prefix rectangle array. The patterns to specify colors and patterns for graphic drawing in a drawing environment are provided. You can either use a provided pattern or register a new pattern with an user application. A pattern ID is given when you register a pattern. Specify this pattern ID to draw with the pattern. Patterns provided in standard specifications are a filling pattern with pixel value of 0 for pattern ID = 0 and a filling pattern with pixel value of 1 for pattern ID = 1. 5.1.3 Panel management function - Scene/Panel section The panel management function provides a function to manage scenes and panels to which events are delivered. A scene has a size of the entire screen and one of several scenes is displayed at most. A panel has an arbitrary size and several panels can be displayed at the same time. Panels are displayed over the scenes, and if there are multiple panels, those panels are also displayed over another panel. When displaying a new panel, the panel is displayed on the top of the other panels. In the entire system, one scene or panel at most will be in input-accepting state to receive events exclusively. If minimum of one panel has been displayed, the panel which is on the top of the other panels will be in input-accepting state. If no panel has been displayed, the scene currently being displayed will be in input-accepting state. Normally, switching scenes and displaying/clearing panels should be done by operating the scene/panel in input-accepting state to switch the input-accepting state to another scene/panel. Scenes and panels are defined as a group of parts. Besides the parts provided by the parts management function and character input function, the parts the panel management function itself owns and the parts created uniquely by an user program can be also used. For a panel, the size of the panel also needs to be specified. When you register a panel/scene, a scene ID/panel ID is given. Use these IDs to operate scenes and panels. Use a system call "gp_swi_scn()" to display a scene. This system call clears the scene being displayed if there is any and displays the specified scene. If there is no panel being displayed at this point, this scene will be in input-accepting state. For displaying a panel , use "gp_app_pnl()". The specified panel will appear on the top of the other panels and be in input-accepting state. To clear a panel, use "gp_dis_pnl()". The specified panel will be cleared and the input-accepting state will switch to another scene/panel as required. System calls "p_act_scn()" and "gp_act_pnl()" are available to receive an event in a scene/panel in input-accepting state. Since you have to specify scene/panel ID by range to use this system call, events for several scenes and panels can be received at the same time. Only the scene/panel in input-accepting state can receive an event. If an event was issued on a part, the part is activated by calling the parts management function. In addition, if you want to use a text box of the character input management function, the coordinates of the text box must be specified by using gp_kps_scn() and gp_kps_pnl(). This sends the key events issued to the text box located at this coordinates. When entering in several text boxes, change the setting of the text box coordinates at the timing such as pressing the button on a text box. 5.1.4 Parts management function The parts management function provides a function to handle various parts unitedly. Creating a part issues a parts ID. Use this ID to display/operate parts. A character string and current value are set to a part and the character string may have different function depending on the part. Current value is a non-negative value indicating its selection state. Current value = 0 normally indicates deselected state. The parts are operated by giving an initial event to "gc_act_par()". An initial event is an event which triggers part operation. Some parts may receive events repeatedly until the part operation is completed before returning. The current value resulting from the operation returns. Normally, the parts management function is called within the panel management function and thus, this function may not have to be directly operated from an application. 5.1.5 Character input management function The character input management function provides text box parts. Although this function is similar to the parts management function, it is different on the point that this function receives key events. Since character strings are edited in text box, a caret which indicates the position to input character is displayed. Left and right caret keys and backspace key can be used for editing. 5.1.6 Data box management function The data box management function provides a function to register data boxes provided in memory or file all at the same time. What can be registered here are the definition data of scenes and panels and the definition data of parts are included in this data. ------------------------------------------------------------------------------ 5.2 GUI Middleware Function System Call List ------------------------------------------------------------------------------ 5.2.1 Event management function system call ------------------------------------------------------------------------------ [Usage and Function] W err = ge_ini_evt(VOID *init) Initializes the event queue management function. This system call must be executed once before calling any other event management function system call. Specify NULL to "init". ------------------------------------------------------------------------------ [Usage and Function] W err = ge_put_evt(EVENT *evt) Issues an event. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_get_evt(EVENT *evt, W tmout, W clr) Obtains an event. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_clr_evt(W all) Clears an event. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_sus_evt(W sus) Prohibits to obtain an event. With sus = 1, the system call "ge_get_evt()" will issue an error and disables event-obtaining. This system call is called from the panel management function since it interrupts the wait state for receiving events. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_ini_inp(VOID *init) Initializes the input device management function. This system call must be executed once before calling any other event management function system call. Specify NULL to "init". ------------------------------------------------------------------------------ [Usage and Function] W err = ge_gen_evt(RAWEVT *evt) Issues a raw event. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_set_pda(PD_ATTR *attr) Sets PD attribute. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_get_pda(PD_ATTR *attr) Obtains PD attribute. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_set_kya(KEY_ATTR *attr) Sets key attribute. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_get_kya(KEY_ATTR *attr) Obtains key attribute. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_set_ktb(W size, TC *table) Sets a key table. ------------------------------------------------------------------------------ [Usage and Function] W err = ge_get_ktb(W size, TC *table) Obtains a key table. 5.2.2 Panel management function - Drawing section system calls ------------------------------------------------------------------------------ [Usage and Function] W err = gp_ini_env(BMP *screen) Initializes drawing function of the panel management function. This system call must be executed once before calling any other panel management function system call. Specifying NULL to "screen" activates the embedded screen driver for PC/AT. Specifying anything other than NULL to "screen" executes drawing by considering the specified bit map as a screen. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_set_ptr(W type, PNT *p) Sets the pointer coordinates. A cross-line pointer appears at the set position. This system call is called from the event management function to move the pointer. ------------------------------------------------------------------------------ [Usage and Function] W gid = gp_cre_env(GENVPAR *par) Creates a drawing environment. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_del_env(W gid) Deletes a drawing environment. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_set_off(W gid, PNT *p) Sets drawing offset. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_get_off(W gid, PNT *p) Obtains drawing offset. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_set_vis(W gid, RECT *r) Sets visible rectangle. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_get_vis(W gid, RECT *r) Obtains visible rectangle. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_set_fra(W gid, RECT *r, W cnt) Sets prefix rectangle array. ------------------------------------------------------------------------------ [Usage and Function] W cnt = gp_get_fra(W gid, RECT *r, W cnt) Obtains prefix rectangle array. ------------------------------------------------------------------------------ [Usage and Function] W pid = gp_cre_pat(PAT *pat) Creates a pattern. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_del_pat(W pid) Deletes a pattern. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_dra_lin(W gid, PNT s, PNT e, UW lattr, W pid, W mode) Draws a line. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_fra_rec(W gid, RECT r, UW lattr, W pid, W mode) Draws a rectangle frame. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_fil_rec(W gid, RECT r, W pid, W mode) Draws inside a rectangle. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_fra_rrc(W gid, W rh, W rv, RECT r, UW lattr, W pid, W mode) Draws a rounded-corner rectangle frame. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_fil_rrc(W gid, W rh, W rv, RECT r, W pid, W mode) Draws inside a rounded-corner rectangle. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_fra_ovl(W gid, RECT r, UW lattr, W pid, W mode) Draws an ellipse frame. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_fil_ovl(W gid, RECT r, W pid, W mode) Draws inside an ellipse. ------------------------------------------------------------------------------ [Usage and Function] W sts = gp_pic_lin(PNT pt, PNT s, PNT e, W width) Picking process on a line. ------------------------------------------------------------------------------ [Usage and Function] W sts = gp_pic_rec(PNT pt, RECT r, W width) Picking process on a rectangle. With width = 0, picking is executed on inside the rectangle. With width > 0, picking is executed on the rectangle frame. ------------------------------------------------------------------------------ [Usage and Function] W sts = gp_pic_rrc(PNT pt, W rh, W rv, RECT r, W width) Picking process on a rounded-corner rectangle. With width = 0, picking is executed on inside the rounded-corner rectangle. With width > 0, picking is executed on the rounded-corner rectangle frame. ------------------------------------------------------------------------------ [Usage and Function] W sts = gp_pic_ovl(PNT pt, RECT r, W width) Picking process on an ellipse. With width = 0, picking is executed on inside the ellipse. With width > 0, picking is executed on the ellipse frame. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_dra_bmp(W gid, BMP *bmp, PNT p, W mode) Draws a bit map. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_set_fon(W gid, FONT *font) Sets fonts. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_dra_stp(W gid, PNT p, TC *str, W len, W pid, W mode) Draws a character string. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_get_str(W gid, TC *str, W len, RECT *r) Obtains a character string area. ------------------------------------------------------------------------------ [Usage and Function] VOID* p = gp_savescreen() Saves the current screen in the memory and returns the address. This system call is called from the panel management function to save the panel background. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_restorescreen(VOID* p) Restores the screen from the memory by giving the address obtained by gp_savescreen(). This system call is called from the panel management function to restore the panel background. 5.2.3 Panel management function - Scene/Panel section system calls Initializes drawing function of the panel management function. This system call must be executed once before calling any other panel management function system call. Specify NULL to "init". ------------------------------------------------------------------------------ [Usage and Function] W err = gp_ini_pnl(VOID *init) Initializes scene/panel function of the panel management function. This system call must be executed once before calling any other panel management function system call. ------------------------------------------------------------------------------ [Usage and Function] W wid = gp_cre_scn(PARTS *parts, W nitem) Creates a scene. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_del_scn(W wid) Deletes a scene. ------------------------------------------------------------------------------ [Usage and Function] W cid = gp_set_scn(W wid, W item, PARTS *parts) Sets a scene. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_swi_scn(W wid) Switches a scene. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_vis_scn(W wid, RECT *r) Sets visible rectangle of a scene. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_kps_scn(W wid, PNT *p) Sets key coordinates of a scene. ------------------------------------------------------------------------------ [Usage and Function] W sts = gp_act_scn(W wids, W wide, EVENT *evt, W* wid, W* item, W tmout) Activates a scene. ------------------------------------------------------------------------------ [Usage and Function] W wid = gp_cre_pnl(RECT *r, PARTS *parts, W nitem) Creates a panel. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_del_pnl(W wid) Deletes a panel. ------------------------------------------------------------------------------ [Usage and Function] W cid = gp_set_pnl(W wid, W item, PARTS *parts) Sets a panel. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_app_pnl(W wid) Displays a panel. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_dis_pnl(W wid) Clears a panel. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_vis_pnl(W wid, RECT *r) Sets visible rectangle of a panel. ------------------------------------------------------------------------------ [Usage and Function] W err = gp_kps_pnl(W wid, PNT *p) Sets key coordinates of a panel. ------------------------------------------------------------------------------ [Usage and Function] W sts = gp_act_pnl(W wids, W wide, EVENT *evt, W* wid, W* item, W tmout) Activates a panel. 5.2.4 Parts management function system calls ------------------------------------------------------------------------------ [Usage and Function] W err = gc_ini_par(VOID *init) Initializes drawing function of the parts management function. This system call must be executed once before calling any other parts management function system call. Specify NULL to "init". ------------------------------------------------------------------------------ [Usage and Function] W cid = gc_cre_par(W gid, PARTS *parts) Registers a part. ------------------------------------------------------------------------------ [Usage and Function] W err = gc_del_par(W cid) Deletes a part. ------------------------------------------------------------------------------ [Usage and Function] W err = gc_dsp_par(W cid, W mode) Displays a part. ------------------------------------------------------------------------------ [Usage and Function] W err = gc_set_par(W cid, TC *str, W val) Sets a part. ------------------------------------------------------------------------------ [Usage and Function] W val = gc_get_par(W cid, TC *str, W size) Obtains a part. ------------------------------------------------------------------------------ [Usage and Function] W val = gc_act_par(W cid, EVENT *evt) Activages a part. 5.2.5 Character input management function system calls ------------------------------------------------------------------------------ [Usage and Function] W cid = gt_cre_par(W gid, PARTS *parts) Creates a text box. ------------------------------------------------------------------------------ [Usage and Function] W err = gt_del_par(W cid) Deletes a text box. ------------------------------------------------------------------------------ [Usage and Function] W err = gt_dsp_par(W cid, W mode) Displays a text box. ------------------------------------------------------------------------------ [Usage and Function] W err = gt_set_par(W cid, TC *str, W val) Sets a text box. ------------------------------------------------------------------------------ [Usage and Function] W val = gt_get_par(W cid, TC *str, W size) Obtains a text box. ------------------------------------------------------------------------------ [Usage and Function] W val = gt_act_par(W cid, EVENT *evt) Activates a text box. 5.2.6 Data box management function system calls ------------------------------------------------------------------------------ [Usage and Function] W cnt = gd_reg_dat(TC *data, W *id, W size) Registers a data box. ------------------------------------------------------------------------------ [Usage and Function] W err = gd_wri_dat(TC *filename, TC *data) Writes a data box in a file. ------------------------------------------------------------------------------ [Usage and Function] W cnt = gd_rea_dat(TC *filename, W *id, W size) Registers a data box from a file. 5.3 Evaluation Driver The library with "GUI middleware function" contains a screen driver for machine compatible with PC/AT for evaluation purpose. It also includes a message handler for accepting raw events to be able to accept inputs from keyboard/PD driver provided as an individual program. These are not delivered as products but attached to facilitate evaluation on PC/AT compatible machine. Evaluation screen driver is built in the GUI middleware and activated when gp_ini_env(NULL), a panel management function system call, is called. Its resolution is 640 * 480 dots and gives images in white-and-black. The pixel value 0 corresponds to white and 1 to black. Evaluation keyboard/PD driver supports 106-type keyboard and PS/2 mouse. These information is sent by using RAWEVT structure which indicates a raw event via ITRON message buffer. To accept a raw event from the evaluation keyboard/PD driver, a system call of init_evtsvr(1) must be issued on GUI middleware side. This starts a task to receive a raw event which arrived the message buffer and to call event management. Note that a key table is set to accept entry of alphabetical upper cases, backspace key and caret key from evaluation keyboard/PD driver when "GUI middleware function" starts. ============================================================================== Appendix 1 GUI middleware function external specifications ============================================================================== (1) Functional description This provides functions related to GUI. The following functions are provided as system calls. (A) Event management function Provides functions to convert an input from an input device into an event, store and sequentially obtain these events. (B) Panel management function Provides functions to draw on screen. This also provides functions to manage scenes/panels. (C) Parts management function Provides functions to manage parts. Parts appear on screen to accept operations ordered by an user. (D) Character input management function Provides functions to accept character inputs. (E) Data box management function Provides functions to create scenes, panels and parts at the same time from a data box created in advance. (2) Input data An application gives the following input data to GUI middleware function. (A) For event management function +----------------------------------------------------------------------------+ |Name |Meaning | |------------------------------+---------------------------------------------| |Event |Pointer to a raw event to be generated | |------------------------------+---------------------------------------------| |Raw event |Pointer to an event to be processed/generated| |------------------------------+---------------------------------------------| |PD attribute |Process setting for a PD event | |------------------------------+---------------------------------------------| |Key attribute |Process setting for a key event | |------------------------------+---------------------------------------------| |Key table size |Size of a key table (unit : tc) | |------------------------------+---------------------------------------------| |Key table |A table which shows correspondence of a key | | |number to a character entered by pressing the| | |key. | +----------------------------------------------------------------------------+ (B) For panel management function +----------------------------------------------------------------------------+ |Name |Meaning | |------------------------------+---------------------------------------------| |Drawing environment creation |Information to create a drawing environment | |information | | |------------------------------+---------------------------------------------| |Drawing environment ID |ID to identify a drawing environment | |------------------------------+---------------------------------------------| |Coordinates |Position specified by horizontal and vertical| | |positions | |------------------------------+---------------------------------------------| |Rectangular area |Area specified by left side horizontal | | |position, top side vertical position, right | | |side horizontal position + 1 and bottom side | | |vertical position + 1 | |------------------------------+---------------------------------------------| |Number of rectangles |The number of prefix rectangle arrays | |------------------------------+---------------------------------------------| |Pattern creation information |Information to create a pattern | |------------------------------+---------------------------------------------| |Pattern ID |ID to identify a pattern | |------------------------------+---------------------------------------------| |Line attribute |Specification of a line width | |------------------------------+---------------------------------------------| |Drawing mode |Specification of an operation with a figure | | |already drawn | |------------------------------+---------------------------------------------| |Horizontal corner-rounding |Horizontal diameter for rounding corners of a| |diameter |rounded-corner rectangle | |------------------------------+---------------------------------------------| |Vertical corner-rounding |Vertical diameter for rounding corners of a | |diameter |rounded-corner rectangle | |------------------------------+---------------------------------------------| |Line width |Specification of a line width | |------------------------------+---------------------------------------------| |Font |Character bit maps placed in order of | | |character code | |------------------------------+---------------------------------------------| |Character string |An array of character codes to be drawn | |------------------------------+---------------------------------------------| |Character string length |Length of a character code array | |------------------------------+---------------------------------------------| |Bit map |A figure represented by a set of points | |------------------------------+---------------------------------------------| |Parts creation information |Information to create a part | |------------------------------+---------------------------------------------| |Number of parts |The number of parts included in a scene/panel| |------------------------------+---------------------------------------------| |Scene ID |ID to identify a scene | |------------------------------+---------------------------------------------| |Item number |The parts number registered in a scene/panel | |------------------------------+---------------------------------------------| |First scene ID |The first ID in the scene ID range | |------------------------------+---------------------------------------------| |Last scene ID |The last ID in the scene ID range | |------------------------------+---------------------------------------------| |Event |Data input from pd/keyboard | |------------------------------+---------------------------------------------| |Timeout |Time specified to wait for an event | |------------------------------+---------------------------------------------| |Panel ID |ID to identify a panel | |------------------------------+---------------------------------------------| |First panel ID |The first ID in the panel ID range | |------------------------------+---------------------------------------------| |Last panel ID |The last ID in the panel ID range | +----------------------------------------------------------------------------+ (C) For parts management function +----------------------------------------------------------------------------+ |Name |Meaning | |------------------------------+---------------------------------------------| |Drawing environment ID |ID to identify a drawing environment | |------------------------------+---------------------------------------------| |Parts creation information |Information to specify parts state, area, | | |etc. | |------------------------------+---------------------------------------------| |Part ID |ID to identify a part | |------------------------------+---------------------------------------------| |Parts state specification |Specification to change parts state | |------------------------------+---------------------------------------------| |Parts character string |Character string registered in a part | |------------------------------+---------------------------------------------| |Parts current value |Value registered in a part | |------------------------------+---------------------------------------------| |Character string area |Area for obtaining a character string | |------------------------------+---------------------------------------------| |Character string size |Length of a character string area (unit : tc)| |------------------------------+---------------------------------------------| |Event |Area where the event is stored | +----------------------------------------------------------------------------+ (D) For character input management function +----------------------------------------------------------------------------+ |Name |Meaning | |------------------------------+---------------------------------------------| |Drawing environment ID |ID to identify a drawing environment | |------------------------------+---------------------------------------------| |Text box creation information |Information to specify text box state, area, | | |etc. | |------------------------------+---------------------------------------------| |Text box ID |ID to identify a text box | |------------------------------+---------------------------------------------| |Text box state specification |Specification to change text box state | |------------------------------+---------------------------------------------| |Text box character string |Character string registered in a text box | |------------------------------+---------------------------------------------| |Text box current value |Caret position in a text box | |------------------------------+---------------------------------------------| |Character string area |Area for obtaining a character string | |------------------------------+---------------------------------------------| |Character string size |Length of a character string area (unit : tc)| |------------------------------+---------------------------------------------| |Event |Area where the event is stored | +----------------------------------------------------------------------------+ o Caret is a vertical bar to indicate the position to enter a character. When caret position is 0, the caret is at the left end. (E) For data box management function +----------------------------------------------------------------------------+ |Name |Meaning | |------------------------------+---------------------------------------------| |Data box |Pointer to data box definition data | |------------------------------+---------------------------------------------| |ID array |Array to store the registered ID | |------------------------------+---------------------------------------------| |Array size |Size of an array | |------------------------------+---------------------------------------------| |File name |File name of a data box | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. (A) For event management function +--------------------------------------------------------------------------+ |Name |Mnemonic| |-----------------------------------------------------------------+--------| |Error codes |err | +--------------------------------------------------------------------------+ (B) For panel management function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Number of rectangles |cnt |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Picking results |sts |W | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Execution results |sts |W | +----------------------------------------------------------------------------+ (C) For parts management function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Current parts value |val |W | +----------------------------------------------------------------------------+ (D) For character input management function +--------------------------------------------------------------------------+ |Name |Mnemonic| |-----------------------------------------------------------------+--------| |Error codes |err | |-----------------------------------------------------------------+--------| |Textbox ID |cid | |-----------------------------------------------------------------+--------| |Current textbox value |val | +--------------------------------------------------------------------------+ (E) For data box management function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Error codes |cnt |W | +----------------------------------------------------------------------------+ o cnt indicates an error code if the value is negative, and indicates the number of registrations if the value is 0 or positive. (4) Exception conditions and restrictions Refer to the corresponding item of the subfunction for details. (5) Remarks Refer to the corresponding item of the subfunction for details. (6) Functional block structure and relations GUI middleware function consists of "Event management function", "Panel management function ", "Parts management function", "Character input management function" and "Data box management function". +----------+ +-------------------------+ |Databox +---------->>|Panel management function| |management| +-------------------------+ |function | ^ ^ ^ | | | | | | | +----------------+ | | | +-->>|Parts management| | | | | |function | | | | | +----------------+ | | | | | | +-------------------+ | |-----------------------|->>|Character input | | | | | |Management function| +----------+ | | +-------------------+ | | ^ | | | +-------------------------+ |Event management function| +-------------------------+ Figure Functional blocks mutual relation in GUI middleware function Panel management function uses event management function, parts management function, character input management function and data box management function. Parts management function uses event management function and data box management function. Character input management function uses event management function and data box management function. ------------------------------------------------------------------------------ Appendix 1.1 Event Management Function ------------------------------------------------------------------------------ (1) Functional description In GUI middleware function, this function stores inputs from input devices as "an event" and obtains events sequentially. (A) Event queue management function Event queue management function sequentially stores and obtains events. This function also clears events. (B) Input device management function Input device management function processes inputs from input devices such as pd and keyboard to generate an event. This function also makes setting regarding processing events. (2) Input data +----------------------------------------------------------------------------+ |Name |Meaning | |------------------------------+---------------------------------------------| |Event |Pointer to a raw event to be generated | |------------------------------+---------------------------------------------| |Raw event |Pointer to an event to be processed/generated| |------------------------------+---------------------------------------------| |PD attribute |Processing setting for a PD event | |------------------------------+---------------------------------------------| |Key attribute |Processing setting for a key event | |------------------------------+---------------------------------------------| |Key table size |Size of a key table (unit : tc) | |------------------------------+---------------------------------------------| |Key table |A table which shows correspondence of a key | | |number to a character entered by pressing the| | |key. | +----------------------------------------------------------------------------+ Refer to the corresponding item of the subfunction for details. (3) Output data +----------------------------------------------------------------------------+ |Name |Nnemonic | |-----------------------------------------------------------------+----------| |Error codes |err | +----------------------------------------------------------------------------+ Contents of error codes +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |ER_OK |Normal termination | |--------------------+-------------------------------------------------------| |ER_ADR |Illegal address | |--------------------+-------------------------------------------------------| |ER_PAR |Illegal parameters | |--------------------+-------------------------------------------------------| |ER_LIMIT |Queue overflows | |--------------------+-------------------------------------------------------| |ER_NONE |No data | |--------------------+-------------------------------------------------------| |ER_BUSY |In use | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum number of events which can exist at the same time is 16 in the entire system. An event cannot be received by specifying a task, and an event is not to be received by several tasks simultaneously. Even a program to generate events cannot be used from interrupt handler. Refer to the corresponding item of the subfunction for details. (5) Remarks No remark (6) Functional block structure and relations Event management function consists of subfunctions; event queue management function and input device management function. +----------------------------------------------------+ |Event management function | | +-------------------+ +--------------------+ | | |Event queue | Event | Input device | | | |management function|<<-----| management function| | | +-------------------+ +--------------------+ | +----------------------------------------------------+ Figure Functional block mutual relation in event management function Input device management function gives an event to event queue management function. Appendix 1.1.1 Event queue management function (1) Functional description In event management function, this function generates, obtains and clears events. The following functions are provided as system calls. (A) Event-generating function Stores the "event" specified by input data in event queue. If the "event" specified in input data is a "null event" or "key repeat event", these events are stored in the event queue management function. (B) Event-obtaining function Obtains an "event" from event queue as output data. If an "event" cannot be obtained even after "time-out" time specified in input data, this function aborts the process without obtaining "event". If an "event" was obtained and "clear specification" specified in input data is valid, the obtained "event" is deleted from event queue. (C) Event-clearning function Deletes an event from event queue according to the "clear method" specified in input data. (2) Input data An application gives the following input data to event queue management function. (A) For event-generating function W err = ge_put_evt(EVENT *evt); typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Event $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Event |Pointer to the event to be generated | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stat contains event time information Following values are available for type in EVENT structure. +----------------------------------------------------------------------------+ |Name | |Concrete content | |------------+--------+------------------------------------------------------| |GE_NULL |0 |Null Event | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press Event | |------------+--------+------------------------------------------------------| |GE_BUTUP |2 |Release Event | |------------+--------+------------------------------------------------------| |GE_KEYDWN |3 |Key down Event | |------------+--------+------------------------------------------------------| |GE_KEYUP |4 |Key up Event | |------------+--------+------------------------------------------------------| |GE_AUTKEY |5 |Key repeat Event | +----------------------------------------------------------------------------+ (B) For event-obtaining function W err = ge_get_evt(EVENT *evt, W tmout, W clr); +----------------------------------------------------------------------------+ |Name |Mnemonic |Type | |--------------------+--------------------------------------------+----------| |Timeout |tmout |W | |--------------------+--------------------------------------------+----------| |Clear specification |clr |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Timeout |Time to wait for event occurence | |--------------------+-------------------------------------------------------| |Clear specification |Delete obtained event | +----------------------------------------------------------------------------+ (C) For event-clearing function W err = ge_clr_evt(W all); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Clear method |all |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Clear method |1:Deletes all the events. 0:Deletes the first event. | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. (A) For event-generating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error Codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal Termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |evt is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |evt->type is illegal. | |--------+--------------------------+------------+--------------------------| |ER_LIMIT|Queue overflows |0xffdc0000 |No space in event queue | +---------------------------------------------------------------------------+ (B) For event-obtaining function typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error Codes |err |W | |---------------------------------------------------------+--------+---------| |Event |evt |EVENT* | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal Termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |evt is NULL | |--------+--------------------------+------------+--------------------------| |ER_NONE |No data |0xffe80000 |Receiving timeout | |--------+--------------------------+------------+--------------------------| |ER_BUSY |In use |0xffd50000 |More than one task try to | | | | |receive the event at the | | | | |same time. | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Event |Received event | +----------------------------------------------------------------------------+ (C) For event-clearing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error Codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal Termination |0 |---- | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 16 events can be stored in event queue. An event cannot be received by specifying a task, and an event is not to be received by several tasks simultaneously. Even a program to generate events cannot be used from interrupt handler. (5) Remark No remark Appendix 1.1.2 Input device management function (1) Functional description In event management function, this function processes inputs from input devices and generates events. The following functions are provided as system calls. (A) Event-creating function Processes the "raw event" specified in input data according to "PD attribute", "Key attribute" and "Key table" set in advance and generates an event by calling "event queue management function". (B) PD-attribute setting function Sets the "PD attribute" specified in input data in input device management function. (C) PD-attribute-obtaining function Takes out the "PD attribute" set in input device management function as output data. (D) Key-attribute-setting function Sets the "Key attribute" specified in input data in input device management function. (E) Key-attribute-obtaining function Takes out the "Key attribute" set in input device management function as output data. (F) Key-table-setting function Sets the "Key table" specified in input data in input device management function. (G) Key-table-obtaining function Takes out the "Key table" set in input device management function as output data. (2) Input data An application gives the following input data to input device management function. (A) For event creation function W err = ge_gen_evt(RAWEVT *evt); typedef struct { W type; W x, y; } RAWEVT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Raw event $ |evt |RAWEVT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Raw event |Pointer to the event to be generated or processed | +----------------------------------------------------------------------------+ Contents of RAWEVT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Raw event type |type |W | |------------------------------------------------------------+--------+------| |Parameter X |x |W | |------------------------------------------------------------+--------+------| |Parameter Y |y |W | +----------------------------------------------------------------------------+ Following values are available for type in RAWEVT structure. +---------------------------------------------------------------------------+ |Name | |Concrete content |Meaning of |Meaning of | | | | |Parameter X |Parameter Y | |------------+--+-------------------+-------------------+-------------------| |GE_RMOVE |0 |Relative movement |Horizontal movement|Vertical movement | |------------+--+-------------------+-------------------+-------------------| |GE_AMOVE |1 |Absolute movement |Horizontal |Vertical coordinate| | | | |coordinate | | |------------+--+-------------------+-------------------+-------------------| |GE_PDBUT |2 |Button operation |Button status |(Not used) | |------------+--+-------------------+-------------------+-------------------| |GE_KEYON |3 |key down |Key code |(Not used) | |------------+--+-------------------+-------------------+-------------------| |GE_KEYOFF |4 |Key release |Key code |(Not used) | +---------------------------------------------------------------------------+ (B) For PD attribute setting function W err = ge_set_pda(PD_ATTR *attr); typedef struct { W sense_x, sense_y; } PD_ATTR; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |PD attribute $ |attr |PD_ATTR* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PD attribute |PD event to be processed or set | +----------------------------------------------------------------------------+ Contents of PD_ATTR structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Horizontal sensitivity |sense_x |W | |------------------------------------------------------------+--------+------| |Vertical sensitivity |sense_y |W | +----------------------------------------------------------------------------+ (C) For PD attribute getting function W err = ge_get_pda(PD_ATTR *attr); typedef struct { W sense_x, sense_y; } PD_ATTR; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |PD attribute $ |attr |PD_ATTR* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PD attribute |PD event to be processed or set | +----------------------------------------------------------------------------+ Contents of PD_ATTR structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Horizontal sensitivity |sense_x |W | |------------------------------------------------------------+--------+------| |Vertical sensitivity |sense_y |W | +----------------------------------------------------------------------------+ (D) For key attribute setting function W err = ge_set_kya(KEY_ATTR *attr); typedef struct { W rep_delay, rep_int; } KEY_ATTR; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Key attribute $ |attr |KEY_ATTR*| +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Key attribute |Key event to be processed or set | +----------------------------------------------------------------------------+ Contents of KEY_ATTR structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Key repeat delay time |rep_delay|W | |------------------------------------------------------------+--------+------| |Key repeat interval |rep_int |W | +----------------------------------------------------------------------------+ (E) For key attribute getting function W err = ge_get_kya(KEY_ATTR *attr); typedef struct { W rep_delay, rep_int; } KEY_ATTR; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Key attribute $ |attr |KEY_ATTR*| +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Key attribute |Key event to be processed or set | +----------------------------------------------------------------------------+ (F) For key table setting function W err = ge_set_ktb(W size, TC *table); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Key table size |size |W | |---------------------------------------------------------+--------+---------| |Key table |table |TC* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Key table size |Size of key table (in TC) | |--------------------+-------------------------------------------------------| |Key table |Table showing the relation a key code and the character| | |which is inputted by pushing the key. | +----------------------------------------------------------------------------+ (G) For key table getting function W cnt = ge_get_ktb(W size, TC *table); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Key table size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Key table size |Size of key table (in TC) | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. (A) For event creation function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |evt is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameter |0xfffe0000 |evt->type is illegal. | |--------+--------------------------+------------+--------------------------| |ER_LIMIT|Queue overflow |0xffdc0000 |No space in event queue | +---------------------------------------------------------------------------+ (B) For PD attribute setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |attr is NULL | +---------------------------------------------------------------------------+ (C) For PD attribute getting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error codes |err |W | |---------------------------------------------------------+--------+---------| |PD attribute |attr |PD_ATTR* | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |attr is NULL | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PD attribute |PD event to be processed or set | +----------------------------------------------------------------------------+ (D) For Key attribute setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |attr is NULL | +---------------------------------------------------------------------------+ (E) For key attribute getting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error codes |err |W | |---------------------------------------------------------+--------+---------| |Key attribute |attr |KEY_ATTR*| +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |atr is NULL | +---------------------------------------------------------------------------+ (F) For key table setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |table is NULL | +---------------------------------------------------------------------------+ (G) For key table getting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |---------------------------------------------------------+--------+---------| |Number of keytables |cnt |W | |---------------------------------------------------------+--------+---------| |Error codes |cnt |W | |---------------------------------------------------------+--------+---------| |Key table |table |TC* | +----------------------------------------------------------------------------+ o Negative cnt is error code, and 0 or positive cnt is number of key tables. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Key table |Table showing the relation a key code and the character| | |which is inputted by pushing the key. | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |table is NULL | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 16 events can be stored in event queue. Even a program to generate events cannot be used from interrupt handler. (5) Remark No remark ------------------------------------------------------------------------------ Appendix 1.2 Panel Management Function ------------------------------------------------------------------------------ (1) Functional description In GUI middleware function, this function draws on screen and manages panels and scenes. (A) Drawing environment management function A function to manage "drawing environment", a virtual screen to support drawing from multiple tasks. (B) Line-drawing function A function to draw a line in "drawing environment". This function also checks whether the specified point overlaps a line or not. (C) Rectangle-drawing function A function to draw a rectangle/rounded-corner rectangle in "drawing environment". This function also checks whether the specified point overlaps a rectangle/rounded-corner rectangle or not. (D) Circle-drawing function A function to draw a circle/an ellipse in "drawing environment". This function also checks whether the specified point overlaps a circle/an ellipse or not. (E) Character-drawing function A function to draw a character string in "drawing environment". This function also obtains the size of the character string. (F) Bit-map-drawing function A function to draw the specified bit map in "drawing environment". (G) Panel-displaying function A function to create, set, obtain, display and activate scenes and panels. (H) Panel-clearing function A function to clear/delete scenes and panels. (2) Input data An application gives the following input data to input panel management function. typedef struct { H x, y; } PNT; typedef struct { H h, v; } SIZE; typedef union { struct { H left, top; H right, bottom; } c; { PNT lefttop; PNT rightbot; } p; } RECT; typedef struct { PNT off; RECT vr; W nfra; RECT fra[0]; } GENVPAR; typedef struct { W type; H h, v; COLOR fgcol, bgcol; UB *mask; } PAT; typedef struct { UW planes; UH pixbits; UH rowbytes; RECT bounds; UB *baseaddr[PLANES]; } BMP; typedef struct { W type; TC start; TC end; SIZE size; UB data[0]; } FONT; typedef struct { W type; RECT r; W val; TC *str; } PARTS; typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment creation information $ |par |GENVPAR*| |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Coordinate $ |p |PNT* | |----------------------------------------------------------+--------+--------| |Rectangle area $ |r |RECT* | |----------------------------------------------------------+--------+--------| |Number of rectangles |cnt |W | |----------------------------------------------------------+--------+--------| |Pattern creation information $ |pat |PAT* | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Coordinate $ |s |PNT | |----------------------------------------------------------+--------+--------| |Coordinate $ |e |PNT | |----------------------------------------------------------+--------+--------| |Line attribute |lattr |UW | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Coordinate $ |pt |PNT | |----------------------------------------------------------+--------+--------| |Line thickness |width |W | |----------------------------------------------------------+--------+--------| |Rectangle area $ |r |RECT | |----------------------------------------------------------+--------+--------| |Horizontal corner-rounding diameter |rh |W | |----------------------------------------------------------+--------+--------| |Vertical corner-rounding diameter |rv |W | |----------------------------------------------------------+--------+--------| |Font $ |font |FONT* | |----------------------------------------------------------+--------+--------| |Coordinate $ |p |PNT | |----------------------------------------------------------+--------+--------| |Character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Length of character strings |len |W | |----------------------------------------------------------+--------+--------| |Bitmap $ |bmp |BMP* | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | |----------------------------------------------------------+--------+--------| |Number of parts |nitem |W | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | |----------------------------------------------------------+--------+--------| |Item number |item |W | |----------------------------------------------------------+--------+--------| |First scene ID |wids |W | |----------------------------------------------------------+--------+--------| |Last scene ID |wide |W | |----------------------------------------------------------+--------+--------| |Event $ |evt |EVENT* | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W* | |----------------------------------------------------------+--------+--------| |Item number |item |W* | |----------------------------------------------------------+--------+--------| |Timeout |tmout |W | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | |----------------------------------------------------------+--------+--------| |First panel ID |wids |W | |----------------------------------------------------------+--------+--------| |Last panel ID |wide |W | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W* | +----------------------------------------------------------------------------+ o Name with "$" has the additional explanation after. o Rectangular area may be a structure or a pointer depending on the system call. Therefore, both cases are mentioned here. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |Information to create drawing environment | |creation information| | |--------------------+-------------------------------------------------------| |Drawing environment |Identifier to identify drawing environments | |ID | | |--------------------+-------------------------------------------------------| |Coordinate |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Number of rectangles|Number of prefix rectangles | |--------------------+-------------------------------------------------------| |Pattern creation |Information to create patterns | |information | | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify patterns | |--------------------+-------------------------------------------------------| |Line attribute |Line thickness specification | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with an already-drawn | | |figure | |--------------------+-------------------------------------------------------| |Horizontal |Horizontal diameter of rounded angles in rounded-corner| |corner-rounding |redtangles | |diameter | | |--------------------+-------------------------------------------------------| |Vertical |Vertical diameter of rounded angles in rounded-corner | |corner-rounding |redtangles | |diameter | | |--------------------+-------------------------------------------------------| |Line thickness |Line thickness specification | |--------------------+-------------------------------------------------------| |Font |Character bit maps placed in order of character code | |--------------------+-------------------------------------------------------| |Character strings |Array of character codes to be drawn | |--------------------+-------------------------------------------------------| |Length of character |Length of array of character codes | |--------------------+-------------------------------------------------------| |Bitmap |A figure represented by a set of points | |--------------------+-------------------------------------------------------| |Parts creation |Information to create parts | |information | | |--------------------+-------------------------------------------------------| |Number of parts |Number of perts included in a scene or a panel | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify scenes | |--------------------+-------------------------------------------------------| |Item number |Parts number registered in a scene or a panel | |--------------------+-------------------------------------------------------| |First scene ID |First scene ID within the scene id range | |--------------------+-------------------------------------------------------| |Last scene ID |Last scene ID within the scene id range | |--------------------+-------------------------------------------------------| |Event |Input data from PD or keyboard | |--------------------+-------------------------------------------------------| |Timeout |Time specification to waite for events | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify panels | |--------------------+-------------------------------------------------------| |First panel ID |First panel ID within panel ID range | |--------------------+-------------------------------------------------------| |Last panel ID |Last panel ID within panel ID range | +----------------------------------------------------------------------------+ Contents of PNT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Horizontal coordinate |x |H | |------------------------------------------------------------+--------+------| |Vertical coordinate |y |H | +----------------------------------------------------------------------------+ Contents of structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Horizontal size |h |H | |------------------------------------------------------------+--------+------| |Vertical size |v |H | +----------------------------------------------------------------------------+ Contents of RECT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Horizontal coordinate of left side |left |H | |------------------------------------------------------------+--------+------| |Vertical coordinate of upper side |top |H | |------------------------------------------------------------+--------+------| |Horizontal coordinate of right side |right |H | |------------------------------------------------------------+--------+------| |Vertical coordinate of lower side |bottom |H | |------------------------------------------------------------+--------+------| |Coordinate of upperleft point |lefttop |PNT | |------------------------------------------------------------+--------+------| |COordinate of lowerright point |rightbot|PNT | +----------------------------------------------------------------------------+ Contents of GENVPAR structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Drawing offset |off |PNT | |------------------------------------------------------------+--------+------| |Displayed rectangles |vr |RECT | |------------------------------------------------------------+--------+------| |Number of prefix rectangles |nfra |W | |------------------------------------------------------------+--------+------| |Array of prefix rectangles |fra |RECT[]| +----------------------------------------------------------------------------+ Contents of PAT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Pattern identification |type |W | |------------------------------------------------------------+--------+------| |Width |h |H | |------------------------------------------------------------+--------+------| |Height |v |H | |------------------------------------------------------------+--------+------| |Foreground color |fgcol |COLOR | |------------------------------------------------------------+--------+------| |Background color |bgclolor|COLOR | |------------------------------------------------------------+--------+------| |Mask |mask |UB* | +----------------------------------------------------------------------------+ o type must be 0. o A bit "1" in mask indicates foreground color and "0" indicates background color. Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ Contents of FONT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Font type |type |W | |------------------------------------------------------------+--------+------| |First character code |start |TC | |------------------------------------------------------------+--------+------| |Last character code |end |TC | |------------------------------------------------------------+--------+------| |Font size |size |SIZE | |------------------------------------------------------------+--------+------| |Font data |data |UB[] | +----------------------------------------------------------------------------+ o type must be 0. Contents of BMP structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Number of planes |planes |UW | |------------------------------------------------------------+--------+------| |Number of pixcel bits |pixbits |UH | |------------------------------------------------------------+--------+------| |Number of horizotal bytes |rowbytes|UH | |------------------------------------------------------------+--------+------| |Bitmap area |bounds |RECT | |------------------------------------------------------------+--------+------| |Bitmap address |baseaddr|UB*[] | +----------------------------------------------------------------------------+ o planes must be 1, pixbits must be 0x0101. Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts strings |str |TC* | +----------------------------------------------------------------------------+ Following values are available for type of PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_NULL |0 |NULL parts | |------------+--------+------------------------------------------------------| |GC_TEXT |0x100 |Character strings parts | |------------+--------+------------------------------------------------------| |GC_RECT |0x101 |Rectangle parts | |------------+--------+------------------------------------------------------| |GC_BMAP |0x102 |Bitmap parts | +----------------------------------------------------------------------------+ o Parts type of parts management program and character input management program can be set also. Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Error code |err |W | |------------------------------------------------------------+--------+------| |Drawing Environment ID |gid |W | |------------------------------------------------------------+--------+------| |Number of rectangles |cnt |W | |------------------------------------------------------------+--------+------| |Pattern ID |pid |W | |------------------------------------------------------------+--------+------| |Picking results |sts |W | |------------------------------------------------------------+--------+------| |Panel ID |wid |W | |------------------------------------------------------------+--------+------| |Scene ID |wid |W | |------------------------------------------------------------+--------+------| |Parts ID |cid |W | |------------------------------------------------------------+--------+------| |Operation results |sts |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |--------+-------------------------------------------------------------------| |Value |Concrete Error Content | |--------+-------------------------------------------------------------------| |ER_OK |Normal termination | |--------+-------------------------------------------------------------------| |ER_ADR |Illegal address | |--------+-------------------------------------------------------------------| |ER_PAR |Illegal parameter | |--------+-------------------------------------------------------------------| |ER_NOSPT|No support | |--------+-------------------------------------------------------------------| |ER_NOSPC|Insufficient system memory | |--------+-------------------------------------------------------------------| |ER_ID |Illegal ID | |--------+-------------------------------------------------------------------| |ER_NONE |No data | |--------+-------------------------------------------------------------------| |ER_MINTR|Operation interrupted | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum number of drawing environments is 100 in the entire system. The maximum of 16 prefix rectangle arrays can be drawn in a drawing environment. The maximum number of patterns is 100 in the entire system. The maximum size of a pattern is 1 - 8 in width and 1 - 16 in height. Since fonts are referred to even after the setting was made, it must not be released. The maximum number of panels and scenes is 64 for total of panels and scenes in the entire system The maximum of 64 parts can be registered for each panel/scene. The maximum number of panels which can be displayed at the same time is 16. Since the definition data of panels/scenes is referred to even after registration, it must not be released. The number of tasks to wait for events at the same time is 64 at most. (5) Remark No remark (6) Functional block structure and relations "Panel management function" consists of the following subfunctions; "drawing environment management function" to manage drawing environments, "line-drawing function", "rectangle-drawing function", "circle-drawing function", "character-drawing function" and "bit-map-drawing function" to draw in drawing environments and "panel-displaying function" and "panel-clearing function" to manage panels and scenes. +-------------------------------------------------------------+ |Panel management function | | | | +---------------------------------------------------------+ | | | Drawing environment management function | | | +---------------------------------------------------------+ | | | | +---------+ +---------+ +---------+ +---------+ +---------+ | | |Line | |Rectangle| |Circle | |Character| |Bitmap | | | |Drawing | |Drawing | |Drawing | |Drawing | |Drawing | | | |Function | |Function | |Function | |Function | |Function | | | +---------+ +---------+ +---------+ +---------+ +---------+ | | ^ ^ ^ ^ ^ | | | | | | | | | +-----------+-----------+-----------+-----------+ | | | | | +----------+ +----------+ | | |Panel | |Panel | | | |Displaying| |Clearing | | | |Function | |Function | | | +----------+ +----------+ | +-------------------------------------------------------------+ Figure. Functional block mutual relation in panel management function Drawing environment management function, line drawing function, rectangle drawing function, circle drawing function, character drawing function and bitmap drawing function do not directly exchange data by calling another subfunction. However, every subfunction shares information on drawing environment management. Panel-displaying function uses line-drawing function, rectangle-drawing function, circle-drawing function, character-drawing function and bit-map-drawing function. Panel-clearing function do not directly exchange data by calling another subfunction. However, panel-displaying function and panel-clearing function share information on panel management. Appendix 1.2.1 Drawing environment management function (1) Functional description In panel management function, this function creates, deletes, sets and obtains a drawing environment. It also creates and deletes a pattern. The following functions are provided as system calls. (A) Drawing-environment-creating function Creates a new drawing environment based on "Drawing environment creation information" specified in input data. It returns "Drawing environment ID" of the created drawing environment as output data. (B) Drawing-environment-deleting function Deletes the drawing environment with "Drawing environment ID" specified in input data. (C) Drawing-offset-setting function Sets the "Drawing offset" specified in input data to the drawing environment with "Drawing environment ID" specified in input data. (D) Drawing-offset-obtaining function Stores the drawing offset of the drawing environment with "Drawing environment ID" specified in input data in the area of "Drawing offset" specified in input data. (E) Visible-rectangle-setting function Sets the "visible rectangle" specified in input data to the drawing environment with "drawing environment ID" specified in input data. (F) Visible-rectangle-obtaining function Stores the visible rectangle of the drawing environment with "Drawing environment ID" specified in input data in the area of "Visible rectangle" specified in input data. (G) Prefix-rectangle-array-setting function Sets the "Prefix rectangle array" specified in input data to the drawing environment with "Drawing environment ID" specified in input data. (H) Forground-rectangle-array-obtaining function Stores the prefix rectangle array of the drawing environment with "Drawing environment ID" specified in input data in the area of "Prefix rectangle array" specified in input data. (I) Pattern-creating function Creates a new pattern based on "Pattern creation information" specified in input data. It returns "Pattern ID" of the created pattern as output data. (J) Pattern-deleting function Deletes the pattern with "Pattern ID" specified in input data. (2) Input data An application gives the following input data to drawing environment management function. (A) For drawing-environment-creating function W gid = gp_cre_env(GENVPAR *par); typedef struct { PNT off; RECT vr; W nfra; RECT fra[0]; } GENVPAR; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment creation information $ |par |GENVPAR*| +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |Information to create a drawing environment | |creation information| | +----------------------------------------------------------------------------+ Contents of GENVPAR structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Drawing offset |off |PNT | |------------------------------------------------------------+--------+------| |Visible rectangle |vr |RECT | |------------------------------------------------------------+--------+------| |Number of prefix rectangles |nfra |W | |------------------------------------------------------------+--------+------| |Array of prefix rectangles |fra |RECT[]| +----------------------------------------------------------------------------+ (B) For drawing-environment-deleting function W err = gp_del_env(W gid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |to identify a drawing environment | |ID | | +----------------------------------------------------------------------------+ (C) For drawing-offset-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Coordinate |p |PNT* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Coordinate |Specification of a position with horizontal and | | |vertical positions | +----------------------------------------------------------------------------+ (D) For drawing-offset-obtaining function W err = gp_get_off(W gid, PNT *p); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Coordinate |p |PNT* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Coordinate |Specification of a position with horizontal and | | |vertical positions | +----------------------------------------------------------------------------+ (E) For visible-rectangle-setting function W err = gp_set_vis(W gid, RECT *r); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | +----------------------------------------------------------------------------+ (F) For visible-rectangle-obtaining function W err = gp_get_vis(W gid, RECT *r); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | +----------------------------------------------------------------------------+ (G) For prefix-rectangle-array-setting function W err = gp_set_fra(W gid, RECT *r, W cnt); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Number of rectangles |cnt |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Number of rectangles|Number of prefix rectangle arrays | +----------------------------------------------------------------------------+ (H) For prefix-rectangle-array-obtaining function W cnt = gp_get_fra(W gid, RECT *r, W cnt); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Number of rectangles |cnt |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Number of rectangles|Number of prefix rectangle arrays | +----------------------------------------------------------------------------+ (I) For pattern-creating function W pid = gp_cre_pat(PAT *pat); typedef struct { W type; H h, v; COLOR fgcol, bgcol; UB *mask; } PAT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Pattern creation information $ |pat |PAT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Pattern creation |Information to create Patterns | |information | | +----------------------------------------------------------------------------+ Contents of PAT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Pattern identification |type |W | |------------------------------------------------------------+--------+------| |Width |h |H | |------------------------------------------------------------+--------+------| |Height |v |H | |------------------------------------------------------------+--------+------| |Forground color |fgcol |COLOR | |------------------------------------------------------------+--------+------| |Background color |bgcol |COLOR | |------------------------------------------------------------+--------+------| |Mask |mask |UB* | +----------------------------------------------------------------------------+ o type must be 0. o A bit "1" in mask indicates foreground color and "0" indicates background color. (J) For pattern-deleting function W err = gp_del_pat(W pid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. (A) For drawing-environment-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |gid |W | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | +----------------------------------------------------------------------------+ o Negative gid is error code, and 0 or positive gid is drawing environment ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |--------+-------------------------------------------------------------------| |ER_OK |Normal termination | |--------+-------------------------------------------------------------------| |ER_ADR |Illegal address | |--------+-------------------------------------------------------------------| |ER_NOSPT|No support | |--------+-------------------------------------------------------------------| |ER_NOSPC|Insufficient system memory | |--------+-------------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (B) For drawing-environment-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |--------+-------------------------------------------------------------------| |ER_OK |Normal termination | |--------+-------------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (C) For drawing-offset-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (D) For drawing-offset-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (E) For visible-rectangle-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (F) For visible-rectangle-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (G) For prefix-rectangle-array-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_NOSPT |ER_NOSPT | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (H) For prefix-rectangle-array-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cnt |W | |----------------------------------------------------------+--------+--------| |Number of rectangles |cnt |W | +----------------------------------------------------------------------------+ o Negative cnt is error code, and 0 or positive cnt is number of rectangles Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (I) For pattern-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |pid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | +----------------------------------------------------------------------------+ o Negative pid is error code, and 0 or positive pid is pettern ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPT |No support | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (J) For pattern-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum number of drawing environments is 100 in the system. The maximum of 16 prefix rectangle arrays can be drawn in a drawing environment. The maximum number of patterns is 100 in the entire system. The maximum size of a pattern is 1 - 8 in width and 1 - 16 in height. (5) Remark No remark Appendix 1.2.2 Line-drawing function (1) Functional description In panel management function, this function draws a line in drawing environment. It also checks whether the specified point overlaps a line or not. The following functions are provided as system calls. (A) Line-drawing function Draws a line in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Coordinates", "Pattern ID" and "Drawing mode" specified in input data. (B) Line-picking function Returns output data for whether "Coordinates" specified in input data exists on the line given by "Coordinates" and "Line width" specified in input data. (2) Input data An application gives the following input data to line-drawing function. (A) For line-drawing function W err = gp_dra_lin(W gid, PNT s, PNT e, UW lattr, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Coordinate |s |PNT | |----------------------------------------------------------+--------+--------| |Coordinate |e |PNT | |----------------------------------------------------------+--------+--------| |Line attribute |lattr |UW | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing enbironment | |ID | | |--------------------+-------------------------------------------------------| |Coordinate |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Line attribute |Line thickness | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with an already-drawn | | |figure | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (B) For line-picking function W sts = gp_pic_lin(PNT pt, PNT s, PNT e, W width); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Coordinate |s |PNT | |----------------------------------------------------------+--------+--------| |Coordinate |e |PNT | |----------------------------------------------------------+--------+--------| |Coordinate |pt |PNT | |----------------------------------------------------------+--------+--------| |Line thickness |width |W | +----------------------------------------------------------------------------+ o Rectangular area may be a structure or a pointer depending on the system call. Therefore, both cases are mentioned here. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern creation |Information to create a pattern | |information | | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Line attribute |Line width specification | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with an already-drawn | | |figure | |--------------------+-------------------------------------------------------| |Horizontal |Horizontal diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | |--------------------+-------------------------------------------------------| |Vertical |Vertical diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | |--------------------+-------------------------------------------------------| |Line thickness |Line width specification | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(A) Line-drawing function", the line is drawn on the screen as a side effect of the system call. (A) For line-drawing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (B) For line-picking function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Picking results |sts |W | +----------------------------------------------------------------------------+ o sts indicates an error code if the value is negative and indicates a picking result if the value is 0 or positive. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions No condition and No restriction. (5) Remark No remark Appendix 1.2.3 Rectangle-drawing function (1) Functional description In panel management function, this function draws a rectangle/rounded-corner rectangle. It also checks whether the specified point overlaps a rectangle/rounded-corner rectangle. The following functions are provided as system calls. (A) Rectangle-frame-drawing function Draws the frame of a rectangle in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Rectangular area", "Line attribute", "Pattern ID" and "Drawing mode" specified in input data. (B) Rectangle-filling function Draws inside a rectangle in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Rectangular area", "Pattern ID" and "Drawing mode" specified in input data. (C) Rectangle-picking function Returns output data for whether "Coordinates" specified in input data exists on the rectangle frame given by "Rectangular area" and "Line width" specified in input data. If "Line width" is 0, it returns whether the specified "Coordinates" exists inside the rectangle or not. (D) Rounded-corner-rectangle-frame-drawing function Draws the frame of a rounded-corner rectangle in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Rectangular area", "Horizontal corner-rounding specification", "Vertical corner-rounding specification", "Line attribute", "Pattern ID" and "Drawing mode" specified in input data. (E) Rounded-corner-rectangle-filling function Draws inside a rounded-corner rectangle in the drawing environment with "Drawing environment ID" specified in input data in accordance with with "Rectangular area", "Horizontal corner-rounding specification", "Vertical corner-rounding specification", "Pattern ID" and "Drawing mode" specified in input data. (F) Rounded-corner-rectangle-picking function Returns output data for whether "Coordinates" specified in input data exists on the rounded-corner rectangle frame given by "Rectangular area", "Horizontal corner-rounding specification", "Vertical corner-rounding specification" and "Line width" specified in input data. If "Line width" is 0, it returns whether the specified "Coordinates" exists inside the rounded-corner rectangle or not. (2) Input data An application gives the following input data to rectangle-drawing function. (A) For rectangle-frame-drawing function W err = gp_fra_rec(W gid, RECT r, UW lattr, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Line attribute |lattr |UW | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Line attribute |Line width specification | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (B) For rectangle-filling function W err = gp_fil_rec(W gid, RECT r, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Line attribute |Line width specification | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (C) For rectangle-picking function W sts = gp_pic_rec(PNT pt, RECT r, W width); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Coordinate |pt |PNT | |----------------------------------------------------------+--------+--------| |Line thickness |whidh |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Line thickness |Line thickness specification | +----------------------------------------------------------------------------+ (D) For rounded-corner-rectangle-frame-drawing function W err = gp_fra_rrc(W gid, W rh, W rv, RECT r, UW lattr, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Line attribute |lattr |UW | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | |----------------------------------------------------------+--------+--------| |Horizontal corner-rounding diameter |rh |W | |----------------------------------------------------------+--------+--------| |Vertical corner-rounding diameter |rv |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Line attribute |Line width specification | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | |--------------------+-------------------------------------------------------| |Horizontal |Horizontal diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | |--------------------+-------------------------------------------------------| |Vertical |Vertical diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (E) For rounded-corner-rectangle-filling function W err = gp_fil_rrc(W gid, W rh, W rv, RECT r, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | |----------------------------------------------------------+--------+--------| |Horizontal corner-rounding diameter |rh |W | |----------------------------------------------------------+--------+--------| |Vertical corner-rounding diameter |rv |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | |--------------------+-------------------------------------------------------| |Horizontal |Horizontal diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | |--------------------+-------------------------------------------------------| |Vertical |Vertical diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (F) For rounded-corner-rectangle-picking function W sts = gp_pic_rrc(PNT pt, W rh, W rv, RECT r, W width); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Coordinate |pt |PNT | |----------------------------------------------------------+--------+--------| |Line thickness |width |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | |----------------------------------------------------------+--------+--------| |Horizontal corner-rounding diameter |rh |W | |----------------------------------------------------------+--------+--------| |Vertical corner-rounding diameter |rv |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Horizontal |Horizontal diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | |--------------------+-------------------------------------------------------| |Vertical |Vertical diameter for rounding corners of a | |corner-rounding |rounded-corner rectangle | |diameter | | |--------------------+-------------------------------------------------------| |Line thickness |Line thickness specification | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(A) Rectangle-frame-drawing function", "(B) Rectangle-filling function", "(D) Rounded-corner-rectangle-frame-drawing function" and "(E) Rounded-corner-rectangle-filling function", the rectangle/rounded-corner rectangle is drawn on screen as a side effect of the system call. (A) Rectangle-frame-drawing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (B) Rectangle-filling function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (C) For rectangle-picking function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |sts |W | |----------------------------------------------------------+--------+--------| |Picking results |sts |W | +----------------------------------------------------------------------------+ o sts indicates an error code if the value is negative and indicates a picking result if the value is 0 or positive. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | +----------------------------------------------------------------------------+ (D) Rounded-corner-rectangle-frame-drawing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (E) Rounded-corner-rectangle-filling function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (F) For rounded-corner-rectangle-picking function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |sts |W | |----------------------------------------------------------+--------+--------| |Picking results |sts |W | +----------------------------------------------------------------------------+ o sts indicates an error code if the value is negative and indicates a picking result if the value is 0 or positive. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions No condition and no restriction (5) Remark No remark Appendix 1.2.4 Circle-drawing function (1) Functional description In panel management function, this function draws a circle/an ellipse in drawing environment. It also checks whether the specified point overlaps a circle/an ellipse. The following functions are provided as system calls. (A) Ellipse-frame-drawing function Draws the frame of an ellipse in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Rectangular area", "Line attribute", "Pattern ID" and "Drawing mode" specified in input data. (B) Ellipse-filling function Draws inside an ellipse in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Rectangular area", "Pattern ID" and "Drawing mode" specified in input data. (C) Ellipse-picking function Returns output data for whether "Coordinates" specified in input data exists on the ellipse frame given by "Rectangular area" and "Line width" specified in input data. If "Line width" is 0, it returns whether the specified "Coordinates" exists inside the ellipse or not. (2) Input data An application gives the following input data to circle-drawing function. (A) For ellipse-frame-drawing function W err = gp_fra_ovl(W gid, RECT r, UW lattr, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Line attribute |lattr |UW | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Line attribute |Line width specification | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (B) Ellipse-filling function W err = gp_fil_ovl(W gid, RECT r, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (C) Ellipse-picking function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Coordinate |pt |PNT | |----------------------------------------------------------+--------+--------| |Line thickness |width |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Line thickness |Line thickness specification | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(A) Ellipse-frame-drawing function" and "(B) Ellipse-filling function", the ellipse is drawn on the screen as a side effect of the system call. (A) Ellipse-frame-drawing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (B) Ellipse-filling function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (C) Ellipse-picking function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |sts |W | |----------------------------------------------------------+--------+--------| |Picking results |sts |W | +----------------------------------------------------------------------------+ o sts indicates an error code if the value is negative and indicates a picking result if the value is 0 or positive. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions No condition and no restriction (5) Remark No remark Appendix 1.2.5 Character-drawing function (1) Functional description In panel management function, this function draws a character string in drawing environment. It also obtains the size of the character string. The following functions are provided as system calls. (A) Font-setting function Sets the "Font" specified in input data to the drawing environment with "Drawing environment ID" specified in input data. (B) Character-string-drawing function Draws a character string in the drawing environment with "Drawing environment ID" specified in input mode in accordance with "Coordinates", "Character string", "Character string length", "Pattern ID" and "Drawing mode" specified in input mode. (C) Character-string-size-obtaining function Stores the rectangular area for drawing the character with "Character string" and "Character length" specified in input data in the drawing environment with "Drawing environment ID" specified in input data in the area of "Rectangular array" specified in input data. (2) Input data An application gives the following input data to character-drawing function. (A) For font-setting function W err = gp_set_fon(W gid, FONT *font); typedef struct { W type; TC start; TC end; SIZE size; UB data[0]; } FONT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Font $ |font |FONT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Font |Character bit maps placed in order of character code | +----------------------------------------------------------------------------+ Contents of FONT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Font identifier |type |W | |------------------------------------------------------------+--------+------| |First character code |start |TC | |------------------------------------------------------------+--------+------| |Last character code |end |TC | |------------------------------------------------------------+--------+------| |Font size |size |SIZE | |------------------------------------------------------------+--------+------| |Font data |data |UB[] | +----------------------------------------------------------------------------+ o type must be 0. (B) For character-string-drawing function W err = gp_dra_stp(W gid, PNT p, TC *str, W len, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Coordinate |p |PNT | |----------------------------------------------------------+--------+--------| |Character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Length of character strings |len |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | |--------------------+-------------------------------------------------------| |Character string |Array of character codes to be drawn | |--------------------+-------------------------------------------------------| |Character string |The length of a character code array | |length | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (C) For character-string-size-obtaining function W err = gp_get_str(W gid, TC *str, W len, RECT *r); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings length |len |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Character string |Array of character codes to be drawn | |--------------------+-------------------------------------------------------| |Character string |The length of a character code array | |length | | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(B) Character-string-drawing function", the character string is drawn on the screen as a side effect of the system call. (A) For font-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (B) Character-string-drawing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (C) For character-string-size-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions Since "Font" is referred to even after setting was made, it must not be released. (5) Remark No remark Appendix 1.2.6 Bit-map-drawing function (1) Functional description In panel management function, this function draws a bit map in drawing environment. The following functions are provided as system calls. (A) Bit-map-drawing function Draws a bit map in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Bit map", "Coordinates" and "Drawing mode" specified in input data. (2) Input data An application gives the following input data to bit-map-drawing function. (A) For bit-map-drawing function W err = gp_dra_bmp(W gid, BMP *bmp, PNT p, W mode); typedef struct { UW planes; UH pixbits; UH rowbytes; RECT bounds; UB *baseaddr[PLANES]; } BMP; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Coordinate |p |PNT | |----------------------------------------------------------+--------+--------| |Bitmap $ |bmp |BMP* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | |--------------------+-------------------------------------------------------| |Bitmap |A figure represented by a set of points | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ Contents of BMP structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Number of planes |planes |UW | |------------------------------------------------------------+--------+------| |Number of pixel bits |pixbits |UH | |------------------------------------------------------------+--------+------| |Number of horizontal bytes |rowbytes|UH | |------------------------------------------------------------+--------+------| |Number of bitmap areas |bounds |RECT | |------------------------------------------------------------+--------+------| |Bitmap address |baseaddr|UB*[] | +----------------------------------------------------------------------------+ o planes must 1 and pixbits must be 0x0101. (3) Output data The following output data is given to an application. In case of "(A) Bit-map-drawing function", the bit map is drawn on the screen as a side effect of the system call. (A) For bit-map-drawing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions No condition and no restriction (5) Remark No remark Appendix 1.2.7 Panel-displaying function (1) Functional description In panel management function, this function creates, displays, sets and obtains scenes and panels. The following functions are provided as system calls. (A) Scene-creating function Creates a scene in accordance with "Scene creation information" specified in input data. The "Scene ID" of the created scene returns as output data. (B) Scene-setting function Replaces the item specified by "Item number" of the scene with "Scene ID" specified in input data with the part given by "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (C) Scene-displaying function Deselects the scene being displayed and displays the scene with "Scene ID" specified in input data. (D) Scene-visible-rectangle-setting function Changes the visible rectangle of the scene with "Scene ID" specified in input data to the "Rectangular area" specified in input data. (E) Scene-key-coordinates-setting function Changes the key coordinates of the scene with "Scene ID" specified in input data to the "Coordinates" specified in input data. (F) Scene-activating function Accepts events for the scenes in the range between "First scene ID" and "Last scene ID" specified in input data for the time of "Time-out". If an event was generated on a part registered in the scene, the part is also activated. The scene ID, item number and event activated are stored in the area of "Scene ID", "Item number" and "Event" specified in input data. (G) Panel-creating function Creates a panel in accordance with "Panel creation information" specified in input data. The "Panel ID" of the created panel returns as output data. (H) Panel-setting function Replaces the item specified by "Item number" of the panel with "Panel ID" specified in input data with the part given by "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (I) Panel-displaying function Displays the panel with "Panel ID" specified in input data on the top. (J) Panel-visible-rectangle-setting function Changes the visible rectangle of the panel with "Panel ID" specified in input data to the "Rectangular area" specified in input data. (K) Panel-key-coordinates-setting function Changes the key coordinates of the panel with "Panel ID" specified in input data to the "Coordinates" specified in input data. (L) Panel-activating function Accepts events for the panels in the range between "First panel ID" and "Last panel ID" specified in input data for the time of "Time-out". If an event was generated on a part registered in the panel, the part is also activated. The panel ID, item number and event activated are stored in the area of "panel ID", "Item number" and "Event" specified in input data. (2) Input data An application gives the following input data to panel-displaying function. (A) For scene-creating function W wid = gp_cre_scn(PARTS *parts, W nitem); typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | |----------------------------------------------------------+--------+--------| |Number of parts |nitem |W | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts creation |Information to create parts | |information | | |--------------------+-------------------------------------------------------| |Number of parts |Number of parts included the scene | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_NULL |0 |NULL parts | |------------+--------+------------------------------------------------------| |GC_TEXT |0x100 |Character strings parts | |------------+--------+------------------------------------------------------| |GC_RECT |0x101 |Rectangle parts | |------------+--------+------------------------------------------------------| |GC_BMAP |0x102 |Bitmap parts | +----------------------------------------------------------------------------+ o Parts type of parts management program and character input management program can be set also. (B) For scene-setting function W cid = gp_set_scn(W wid, W item, PARTS *parts); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | |----------------------------------------------------------+--------+--------| |Item number |item |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts creation |Information to creat parts | |information | | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | |--------------------+-------------------------------------------------------| |Item number |Parts number registered in the scene | +----------------------------------------------------------------------------+ (C) For scene-displaying function W err = gp_swi_scn(W wid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | +----------------------------------------------------------------------------+ (D) For scene-visible-rectangle-setting function W err = gp_vis_scn(W wid, RECT *r); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | +----------------------------------------------------------------------------+ (E) For scene-key-coordinates-setting function W err = gp_kps_scn(W wid, PNT *p); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Coordinate |p |PNT | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | +----------------------------------------------------------------------------+ (F) For scene-activating function W sts = gp_act_scn(W wids, W wide, EVENT *evt, W* wid, W* item, W tmout); typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |First scene ID |wids |W | |----------------------------------------------------------+--------+--------| |Last scene ID |wide |W | |----------------------------------------------------------+--------+--------| |Event $ |evt |EVENT* | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W* | |----------------------------------------------------------+--------+--------| |Item number |item |W* | |----------------------------------------------------------+--------+--------| |Timeout |tmout |W | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | |--------------------+-------------------------------------------------------| |Item number |Parts number registered in a scene or a panel | |--------------------+-------------------------------------------------------| |First scene ID |First scene ID within panel ID range | |--------------------+-------------------------------------------------------| |Last scene ID |Last scene ID within panel ID range | |--------------------+-------------------------------------------------------| |Event |Input data from PD or keyboard | |--------------------+-------------------------------------------------------| |Timeout |Time specification to waite for events | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ (G) For panel-creating function W wid = gp_cre_pnl(RECT *r, PARTS *parts, W nitem); typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | |----------------------------------------------------------+--------+--------| |Number of parts |nitem |W | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Parts creation |Information to create parts | |information | | |--------------------+-------------------------------------------------------| |Number of parts |Number of parts included the panel | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_NULL |0 |NULL parts | |------------+--------+------------------------------------------------------| |GC_TEXT |0x100 |Character strings parts | |------------+--------+------------------------------------------------------| |GC_RECT |0x101 |Rectangle parts | |------------+--------+------------------------------------------------------| |GC_BMAP |0x102 |Bitmap parts | +----------------------------------------------------------------------------+ o Parts type of parts management program and character input management program can be set also. (H) For panel-setting function W cid = gp_set_pnl(W wid, W item, PARTS *parts); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | |----------------------------------------------------------+--------+--------| |Item number |item |W | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts creation |Information to create parts | |information | | |--------------------+-------------------------------------------------------| |Item nubmer |Parts number registered a panel | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | +----------------------------------------------------------------------------+ (I) For panel-displaying function W err = gp_app_pnl(W wid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify a panel | +----------------------------------------------------------------------------+ (J) For panel-visible-rectangle-setting function W err = gp_vis_pnl(W wid, RECT *r); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Rectangle area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify a panel | +----------------------------------------------------------------------------+ (K) For panel-key-coordinates-setting function W err = gp_kps_pnl(W wid, PNT *p); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Coordinates |p |PNT* | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Coordinates |Specification of a position with horizontal and | | |vertical positions | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify a panel | +----------------------------------------------------------------------------+ (L) For panel-activating function W sts = gp_act_pnl(W wids, W wide, EVENT *evt, W* wid, W* item, W tmout); typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Event $ |evt |EVENT* | |----------------------------------------------------------+--------+--------| |Item number |item |W* | |----------------------------------------------------------+--------+--------| |Timeout |tmout |W | |----------------------------------------------------------+--------+--------| |First panel ID |wids |W | |----------------------------------------------------------+--------+--------| |Last panel ID |wid |W | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Item number |Parts number registered in a scene or a panel | |--------------------+-------------------------------------------------------| |Event |Input data from PD or keyboard | |--------------------+-------------------------------------------------------| |Event |Input data from PD or keyboard | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify a panel | |--------------------+-------------------------------------------------------| |First panel ID |First panel ID within panel ID range | |--------------------+-------------------------------------------------------| |Last panel ID |Last panel ID within panel ID range | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. (A) For scene-creating function (4) Exception conditions and restrictions No condition and no restriction (5) Remark No remark Appendix 1.2.5 Character-drawing function (1) Functional description In panel management function, this function draws a character string in drawing environment. It also obtains the size of the character string. The following functions are provided as system calls. (A) Font-setting function Sets the "Font" specified in input data to the drawing environment with "Drawing environment ID" specified in input data. (B) Character-string-drawing function Draws a character string in the drawing environment with "Drawing environment ID" specified in input mode in accordance with "Coordinates", "Character string", "Character string length", "Pattern ID" and "Drawing mode" specified in input mode. (C) Character-string-size-obtaining function Stores the rectangular area for drawing the character with "Character string" and "Character length" specified in input data in the drawing environment with "Drawing environment ID" specified in input data in the area of "Rectangular array" specified in input data. (2) Input data An application gives the following input data to character-drawing function. (A) For font-setting function W err = gp_set_fon(W gid, FONT *font); typedef struct { W type; TC start; TC end; SIZE size; UB data[0]; } FONT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Font $ |font |FONT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Font |Character bit maps placed in order of character code | +----------------------------------------------------------------------------+ Contents of FONT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Font identifier |type |W | |------------------------------------------------------------+--------+------| |First character code |start |TC | |------------------------------------------------------------+--------+------| |Last character code |end |TC | |------------------------------------------------------------+--------+------| |Font size |size |SIZE | |------------------------------------------------------------+--------+------| |Font data |data |UB[] | +----------------------------------------------------------------------------+ o type must be 0. (B) For character-string-drawing function W err = gp_dra_stp(W gid, PNT p, TC *str, W len, W pid, W mode); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Pattern ID |pid |W | |----------------------------------------------------------+--------+--------| |Drawing mode |mode |W | |----------------------------------------------------------+--------+--------| |Coordinate |p |PNT | |----------------------------------------------------------+--------+--------| |Character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Length of character strings |len |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Pattern ID |ID to identify a pattern | |--------------------+-------------------------------------------------------| |Drawing mode |Specification of an operation with already-drawn | | |figures | |--------------------+-------------------------------------------------------| |Character string |Array of character codes to be drawn | |--------------------+-------------------------------------------------------| |Character string |The length of a character code array | |length | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |G_STORE |0 |Draw as it is. | |------------+--------+------------------------------------------------------| |G_XOR |1 |Draw after XOR operation | |------------+--------+------------------------------------------------------| |G_OR |2 |Draw after OR operation | |------------+--------+------------------------------------------------------| |G_AND |3 |Draw after AND operation | |------------+--------+------------------------------------------------------| |G_CPYN |4 |Inverted drawing | |------------+--------+------------------------------------------------------| |G_XORN |5 |XOR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ORN |6 |OR drawing with inverted data | |------------+--------+------------------------------------------------------| |G_ANDN |7 |AND drawing with inverted data | +----------------------------------------------------------------------------+ (C) For character-string-size-obtaining function W err = gp_get_str(W gid, TC *str, W len, RECT *r); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Rectangle area |r |RECT* | |----------------------------------------------------------+--------+--------| |Character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings length |len |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Rectangular area |Specification of an area with left side horizontal | | |position, top side vertical position, right side | | |horizontal position + 1 and bottom side vertical | | |position + 1 | |--------------------+-------------------------------------------------------| |Character string |Array of character codes to be drawn | |--------------------+-------------------------------------------------------| |Character string |The length of a character code array | |length | | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(B) Character-string-drawing function", the character string is drawn on the screen as a side effect of the system call. (A) For font-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | +----------------------------------------------------------------------------+ o Negative wid is error code, and 0 or positive wid is scene ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | +----------------------------------------------------------------------------+ (B) For scene-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (C) For scene-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (D) For scene-visible-rectangle-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal Address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (E) For scene-key-coordinates-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal Address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (F) For scene-activating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Operation results |sta |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_NONE |No data | |----------+-----------------------------------------------------------------| |ER_MINTER |Operation interrupted | +----------------------------------------------------------------------------+ (G) For panel-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ o Negative wid is error code, and 0 or positive wid is parts ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | +----------------------------------------------------------------------------+ (H) For panel-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (I) For panel-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal Parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (J) For panel-visible-rectangle-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal Address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (K) For panel-key-coordinates-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal Address | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (L) For panel-activating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Operation results |sts |W | +----------------------------------------------------------------------------+ o Negative sts is error code, and 0 or positive sts is parts ID. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_NONE |No data | |----------+-----------------------------------------------------------------| |ER_MINTER |Operation interrupted | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum number of panels and scenes is 64 for total of panels and scenes in the entire system. The maximum of 64 parts can be registered for each panel/scene. The maximum number of panels which can be displayed at the same time is 16. Since the definition data of panels/scenes is referred to even after registration, it must not be released. The number of tasks to wait for events at the same time is 64 at most. (5) Remark No remark Appendix 1.2.8 Panel-clearing function (1) Functional description In panel management function, this function clears and deletes scenes and panels. The following functions are provided as system calls. (A) Scene-deleting function Deletes the scene with "Scene ID" specified in input data. (B) Panel-clearing function Clears the panel with "Panel ID" specified in input data. (C) Panel-deleting function Deletes the panel with "Panel ID" specified in input data. (2) Input data An application gives the following input data to panel-clearing function. (A) For scene-deleting function W err = gp_del_scn(W wid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Scene ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Scene ID |ID to identify a scene | +----------------------------------------------------------------------------+ (B) For panel-clearing function W err = gp_del_pnl(W wid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify a panel | +----------------------------------------------------------------------------+ (C) For panel-deleting function W err = gp_dis_pnl(W wid); +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Panel ID |wid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Panel ID |ID to identify a Panel | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. (A) For scene-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (B) For panel-clearing function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal Parameters | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (C) For panel-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions No condition and no restriction (5) Remark No remark Appendix 1.3 Parts Management Function (1) Functional description In GUI middleware function, this function manages parts. The following functions are provided as system calls. (A) Momentary switch management function Creates, deletes, displays, sets, obtains and activates a momentary switch. A momentary switch is a part which detects a click-operation on the switch. (B) Alternate switch management function Creates, deletes, displays, sets, obtains and activates an alternate switch. An alternate switch switches ON/OFF by a click-operation on the switch. (C) Switch selector management function Creates, deletes, displays, sets, obtains and activates a switch selector. A switch selector is a part which displays several choices to allow an user to make selection. (D) Scroll selector management function Creates, deletes, displays, sets, obtains and activates a scroll selector. A scroll selector is a part which displays several choices in scrollable area to allow an user to make selection. (E) Serial selector management function Creates, deletes, displays, sets, obtains and activates a serial selector. A serial selector is a part which displays one of several choices and allows an user to select previous/next choice by switch. (F) Volume management function Creates, deletes, displays, sets, obtains and activates volume. Volume is a part which displays and sets continuous values in a certain range. (2) Input data An application gives the following input data to parts management function. typedef struct { W type; RECT r; W val; TC *str; } PARTS; typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | |----------------------------------------------------------+--------+--------| |parts character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | |----------------------------------------------------------+--------+--------| |Event $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Parts status |Specification to change parts status | |specification | | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in parts | |--------------------+-------------------------------------------------------| |Character strings |Area to obtain charcter strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings (in TC) | |size | | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. More than one parts are separated with MC_STR. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_MSPARTS |2 |Momentary switch | |------------+--------+------------------------------------------------------| |GC_ASPARTS |3 |Alternate switch | |------------+--------+------------------------------------------------------| |GC_WSPARTS |4 |Switch selector | |------------+--------+------------------------------------------------------| |GC_SSPARTS |5 |Scroll selector | |------------+--------+------------------------------------------------------| |GC_ESPARTS |6 |Serial selector | |------------+--------+------------------------------------------------------| |GC_VLPARTS |7 |Volume | |------------+--------+------------------------------------------------------| |GC_HALIGN |0x20 |Horizontal alignment | |------------+--------+------------------------------------------------------| |GC_DOUBLE |0x40 |Two column alignment | |------------+--------+------------------------------------------------------| |GC_NONOB |0x80 |No tombow | |------------+--------+------------------------------------------------------| |GC_NOSE |0x80 |No-item-selectin enableed | |------------+--------+------------------------------------------------------| |GC_EMPHAS |0x200 |Emphasized Frame | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ o GC_NONOB is used for a volume only. GC_NOSEL is used for a switch selector and a scroll selector. So, Same number is available for both without amy problem. Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_EMPHAS |0x200 |Emphasized frame | |------------+--------+------------------------------------------------------| |GC_NORMAL |0x2 |Normal flame | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinates |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o If the parts are operated successfully, GC_ACT(0x1000) is ORed to val. Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. For momentary switch, alternate switch, switch selector, scroll selector and serial selector, the area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. (5) Remarks No remark (6) Functional block structure and relations Parts management function consists of subfunctions; "Momentary switch management function", "Alternate switch management function", "Switch selector management function", "Scroll selector management function", "Serial selector management function" and "Volume management function". +----------------------------------------------------+ | Parts management fucntion | | +---------------------+ +---------------------+ | | | Momentary switch | | Alternate switch | | | | management function | | management function | | | +---------------------+ +---------------------+ | | | | +---------------------+ +---------------------+ | | | Switch selector | | Scroll selector | | | | management function | | management function | | | +---------------------+ +---------------------+ | | | | +---------------------+ +---------------------+ | | | Serial selector | | Volume | | | | management function | | management function | | | +---------------------+ +---------------------+ | +----------------------------------------------------+ Figure Functional block mutual relation in parts management function Momentary switch management function, alternate switch management function, switch selector management function, scroll selector management function, serial selector management function and volume management function do not directly exchange data by calling another subfunction. However, every subfunction shares the information on parts management. Appendix 1.3.1 Momentary switch management function (1) Functional description In parts management function, this function manages momentary switches. The following functions are provided as system calls. (A) Momentary-switch-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Momentary-switch-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Momentary-switch-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Momentary-switch-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Momentary-switch-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Momentary-switch-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to momentary switch management function. (A) For momentary-switch-creating function W cid = gc_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_MSPARTS |2 |Momentary switch | |------------+--------+------------------------------------------------------| |GC_EMPHAS |0x200 |Emphasized Frame | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For momentary-switch-deleting function W err = gc_del_par(W cid) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | +----------------------------------------------------------------------------+ (C) For momentary-switch-displaying function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Parts status |Specification to change parts status. | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_EMPHAS |0x200 |Emphasized frame | |------------+--------+------------------------------------------------------| |GC_NORMAL |0x2 |Normal flame | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For momentary-switch-setting function W err = gc_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts character strings |star |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in the parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in the parts | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (E) For momentary-switch-obtaining function W val = gc_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (F) For momentary-switch-operating function W val = gc_act_par(W cid, EVENT *evt) typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PartsID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Alternate-switch-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For momentary-switch-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For momentary-switch-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For momentary-switch-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For momentary-switch-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For momentary-switch-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For momentary-switch-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. (5) Remark No remark Appendix 1.3.2 Alternate switch management function (1) Functional description In parts management function, this function manages alternate switches. The following functions are provided as system calls. (A) Alternate-switch-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Alternate-switch-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Alternate-switch-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Alternate-switch-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Alternate-switch-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Alternate-switch-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to alternate switch management function. (A) For alternate-switch-creating function W cid = gc_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Alternate-switch-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For momentary-switch-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For momentary-switch-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For momentary-switch-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For momentary-switch-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For momentary-switch-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For momentary-switch-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. (5) Remark No remark Appendix 1.3.2 Alternate switch management function (1) Functional description In parts management function, this function manages alternate switches. The following functions are provided as system calls. (A) Alternate-switch-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Alternate-switch-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Alternate-switch-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Alternate-switch-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Alternate-switch-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Alternate-switch-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to alternate switch management function. (A) For alternate-switch-creating function W cid = gc_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Alternate-switch-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For momentary-switch-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For momentary-switch-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For momentary-switch-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For momentary-switch-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For momentary-switch-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For momentary-switch-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. (5) Remark No remark Appendix 1.3.2 Alternate switch management function (1) Functional description In parts management function, this function manages alternate switches. The following functions are provided as system calls. (A) Alternate-switch-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Alternate-switch-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Alternate-switch-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Alternate-switch-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Alternate-switch-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Alternate-switch-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to alternate switch management function. (A) For alternate-switch-creating function W cid = gc_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_ASPARTS |3 |Alternate switch | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For alternate-switch-deleting function W err = gc_del_par(W cid) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | +----------------------------------------------------------------------------+ (C) For alternate-switch-displaying function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |parts status |Specification to change parts status | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For alternate-switch-setting function W err = gc_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in parts | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (E) For alternate-switch-obtaining function W val = gc_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Character strings |Area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit:TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (F) For alternate-switch-operating function W val = gc_act_par(W cid, EVENT *evt) typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PartsID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Alternate-switch-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For alternate-switch-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For alternate-switch-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For alternate-switch-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For alternate-switch-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For alternate-switch-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For alternate-switch-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. Appendix 1.3.3 Switch selector management function (1) Functional description In parts management function, this function manages switch selectors. The following functions are provided as system calls. (A) Switch-selector-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Switch-selector-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Switch-selector-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Switch-selector-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Switch-selector-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Switch-selector-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to switch selector management function. (A) For switch-selector-creating function W cid = gc_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_SSPARTS |5 |Alternate switch | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For switch-selector-deleting function W err = gc_del_par(W cid) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | +----------------------------------------------------------------------------+ (C) For switch-selector-displaying function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |parts status |Specification to change parts status | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For switch-selector-setting function W err = gc_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in parts | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (E) For switch-selector-obtaining function W val = gc_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Character strings |Area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit:TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (F) For switch-selector-operating function W val = gc_act_par(W cid, EVENT *evt) typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PartsID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Switch-selector-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For switch-selector-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For switch-selector-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For switch-selector-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For switch-selector-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For switch-selector-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For switch-selector-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. Appendix 1.3.4 Scroll selector management function (1) Functional description In parts management function, this function manages scroll selectors. The following functions are provided as system calls. (A) Scroll-selector-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Scroll-selector-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Scroll-selector-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Scroll-selector-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Scroll-selector-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Scroll-selector-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to scroll selector management function. (A) For scroll-selector-creating function typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_SSPARTS |5 |Alternate switch | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For scroll-selector-deleting function W err = gc_del_par(W cid) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | +----------------------------------------------------------------------------+ (C) For scroll-selector-displaying function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |parts status |Specification to change parts status | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For scroll-selector-setting function W err = gc_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in parts | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (E) For scroll-selector-obtaining function W val = gc_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Character strings |Area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit:TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (F) For scroll-selector-operating function W val = gc_act_par(W cid, EVENT *evt) typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PartsID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Scroll-selector-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For scroll-selector-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For scroll-selector-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For scroll-selector-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For scroll-selector-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For scroll-selector-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For scroll-selector-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive val is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. Appendix 1.3.5 Serial selector management function (1) Functional description In parts management function, this function manages serial selectors. The following functions are provided as system calls. (A) Serial-selector-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Serial-selector-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Serial-selector-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Serial-selector-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Serial-selector-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Serial-selector-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to serial selector management function. (A) For serial-selector-creating function typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_SSPARTS |5 |Alternate switch | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For serial-selector-deleting function W err = gc_del_par(W cid) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | +----------------------------------------------------------------------------+ (C) For serial-selector-displaying function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |parts status |Specification to change parts status | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For serial-selector-setting function W err = gc_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in parts | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (E) For serial-selector-obtaining function W val = gc_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Character strings |Area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit:TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (F) For serial-selector-operating function W val = gc_act_par(W cid, EVENT *evt) typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PartsID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Serial-selector-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For serial-selector-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For serial-selector-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For serial-selector-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For serial-selector-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For serial-selector-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive cid is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For serial-selector-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive cid is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. If a character string cannot be displayed within the specified area, the operation is not guaranteed. The area indicated by "str" is referred to when displaying the part. Therefore, they must not be released until the part is deleted. Appendix 1.3.6 Volume management function (1) Functional description In parts management function, this function manages volumes. The following functions are provided as system calls. (A) Volume-creating function Creates a part in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Parts creation information" specified in input data. The parts ID of the part created returns as output data. (B) Volume-deleting function Deletes the part indicated by "Parts ID" specified in input data. (C) Volume-displaying function Changes the state of the part indicated by "Parts ID" specified in input data in accordance with "Parts state specification" specified in input data and displays the part on the screen. (D) Volume-setting function Replaces the contents of the part indicated by "Parts ID" specified in input data with the contents of "Parts character string" and "Parts current value" specified in input data. (E) Volume-obtaining function Returns the contents of the part indicated by "Parts ID" specified in input data as output data. (F) Volume-operating function Operates the part indicated by "Parts ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to volume management function. (A) For volume-creating function W cid = gc_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Parts creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Parts creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Parts type |type |W | |------------------------------------------------------------+--------+------| |Parts area |r |RECT | |------------------------------------------------------------+--------+------| |Parts initial value |val |W | |------------------------------------------------------------+--------+------| |Parts character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_SSPARTS |5 |Alternate switch | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For volume-deleting function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | +----------------------------------------------------------------------------+ (C) For volume-displaying function W err = gc_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |parts status |Specification to change parts status | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For volume-setting function W err = gc_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Parts character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Parts character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Parts current value |Value registered in parts | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (E) For volume-obtaining function W val = gc_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Character strings |Area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit:TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. (F) For volume-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |PartsID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Volume-displaying function", the part is displayed on the screen as a side effect of the system call. (A) For volume-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Parts ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is parts ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For volume-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For volume-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For volume-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For volume-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive cid is parts current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Parts ID |ID to identify Parts | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For volume-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Parts current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive cid is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions Maximum of 256 parts can be created in the entire system. (5) Remark No remark Appendix 1.4 Character Input Management Function (1) Functional description In GUI middleware function, this provides functions related to character inputs. The following functions are provided as system calls. (A) Text box management function Provides text box function as a part to input/edit characters. (A) For text box management function (2) Input data An application gives the following input data to character input management function. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify a drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Text box creation |Information to specify text box state, area, etc. | |information | | |--------------------+-------------------------------------------------------| |Text box ID |ID to identify a text box | |--------------------+-------------------------------------------------------| |Text box state |Specification to change text box state | |specification | | |--------------------+-------------------------------------------------------| |Text box character |Character string registered in the text box | |string | | |--------------------+-------------------------------------------------------| |Text box current |Caret position in the text box | |value | | |--------------------+-------------------------------------------------------| |Character string |Area to obtain a character string | |area | | |--------------------+-------------------------------------------------------| |Character string |Length of the character string area (unit : TC) | |size | | |--------------------+-------------------------------------------------------| |Event |Area where the event is stored | +----------------------------------------------------------------------------+ Refer to the section of the corresponding subfunction for details. (3) Output data The following output data is given to an application. +----------------------------------------------------------------------------+ |Name |Mnemonic| |-------------------------------------------------------------------+--------| |Error codes |err | |-------------------------------------------------------------------+--------| |Text box ID |cid | |-------------------------------------------------------------------+--------| |Text box current value |val | +----------------------------------------------------------------------------+ Contents of Error codes : +----------------------------------------------------------------------------+ |Name |Meaning | |----------+-----------------------------------------------------------------| |ER_OK |Normal termination | |----------+-----------------------------------------------------------------| |ER_ADR |Illegal address | |----------+-----------------------------------------------------------------| |ER_PAR |Illegal parameter | |----------+-----------------------------------------------------------------| |ER_NOSPC |Insufficient system memory | |----------+-----------------------------------------------------------------| |ER_ID |Illegal ID | +----------------------------------------------------------------------------+ Refer to the section of the corresponding subfunction for details. (4) Exception conditions and restrictions The maximum total number of text boxes and parts in parts management program is 256 in the entire system. If a text box character string is too long to be displayed completely, the part which exceeds the maximum string length is not displayed. The longest character string length is 20 characters. (5) Remark No Remark (6) Functional block structure and relations Character input management function consists of text box management function, a subfunction. +-------------------------------------+ | Character Input Management Function | | | | +------------------------------+ | | | Text box management function | | | +------------------------------+ | +-------------------------------------+ Figure Functional block mutual relation in character input management function Appendix 1.4.1 Text box management function (1) Functional description In character input management function, this provides functions related to character inputs. The following functions are provided as system calls. (A) Text-box-creating function Creates a text box in the drawing environment with "Drawing environment ID" specified in input data in accordance with "Text box creation information" specified in input data. The text box ID of the text box created returns as output data. (B) Text-box-deleting function Deletes the text box indicated by "Text box ID" specified in input data. (C) Text-box-displaying function Changes the state of the text box indicated by "Text box ID" specified in input data in accordance with "Text box state specification" specified in input data and displays the text box on the screen. (D) Text-box-setting function Replaces the contents of the text box indicated by "Text box ID" specified in input data with the contents of "Text box character string" and "Text box current value" specified in input data. (E) Text-box-obtaining function Returns the contents of the text box indicated by "Text box ID" specified in input data as output data. (F) Text-box-operating function Operates the text box indicated by "Text box ID" specified in input data according to "Event" specified in input data. The result of the operation returns as output data. (2) Input data An application gives the following input data to text box management function. (A) For text-box-creating function W cid = gt_cre_par(W gid, PARTS *parts) typedef struct { W type; RECT r; W val; TC *str; } PARTS; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Drawing environment ID |gid |W | |----------------------------------------------------------+--------+--------| |Textbox creation information $ |parts |PARTS* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Drawing environment |ID to identify drawing environment | |ID | | |--------------------+-------------------------------------------------------| |Text box creation |Information to specify parts status and their area. | |information | | +----------------------------------------------------------------------------+ Contents of PARTS structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Text box type |type |W | |------------------------------------------------------------+--------+------| |Text box area |r |RECT | |------------------------------------------------------------+--------+------| |Text initial value |val |W | |------------------------------------------------------------+--------+------| |Text box character strings |str |TC* | +----------------------------------------------------------------------------+ o Set TNULL at the end of the parts character strings. Following values are available for type in PARTS structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_TBPARTS1 |1 |Text box | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | +----------------------------------------------------------------------------+ (B) For text-box-deleting function W err = gt_del_par(W cid) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Text box ID |cid |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Text box ID |ID to identify parts | +----------------------------------------------------------------------------+ (C) For text-box-displaying function W err = gt_dsp_par(W cid, W mode) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Text box ID |cid |W | |----------------------------------------------------------+--------+--------| |Text box status specification |mode |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Text box ID |ID to identify Text box | |--------------------+-------------------------------------------------------| |Text box status |Specification to change parts status | |specification | | +----------------------------------------------------------------------------+ Following values are available for mode : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GC_DISABLE |0x800 |Disabled status | |------------+--------+------------------------------------------------------| |GC_ENABLE |0x8 |Enabled status | +----------------------------------------------------------------------------+ (D) For text-box-setting function W err = gt_set_par(W cid, TC *str, W val) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Text box ID |cid |W | |----------------------------------------------------------+--------+--------| |Text box character strings |str |TC* | |----------------------------------------------------------+--------+--------| |Text box current value |val |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Text box ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Text box character |Character strings registered in parts | |strings | | |--------------------+-------------------------------------------------------| |Text box current |Value registered in parts | |value | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the text box character strings. (E) For text-box-obtaining function W val = gt_get_par(W cid, TC *str, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Text box ID |cid |W | |----------------------------------------------------------+--------+--------| |Text box strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Text box strings size |size |W | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Text box ID |ID to identify parts | |--------------------+-------------------------------------------------------| |Text box strings |Area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Text box strings |Length of character strings area (Unit:TC) | |size | | +----------------------------------------------------------------------------+ o Set TNULL at the end of the text box character strings. Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | |------------+--------+------------------------------------------------------| |GE_KEYDWN |3 |Key down event | |------------+--------+------------------------------------------------------| |GE_AUTKEY |5 |Key repeat event | +----------------------------------------------------------------------------+ (F) For text-box-operating function W val = gt_act_par(W cid, EVENT *evt) typedef struct { W type; PNT pos; TC key; UW stat; } EVENT; +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Text box ID |cid |W | |----------------------------------------------------------+--------+--------| |EVENT $ |evt |EVENT* | +----------------------------------------------------------------------------+ Name with "$" has the additional explanation after. +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Text box ID |Parts to identify parts | |--------------------+-------------------------------------------------------| |Event |Area in which an event is stored | +----------------------------------------------------------------------------+ Contents of EVENT structure : +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |------------------------------------------------------------+--------+------| |Event type |type |W | |------------------------------------------------------------+--------+------| |Event coordinate |pos |PNT | |------------------------------------------------------------+--------+------| |Event character |key |TC | |------------------------------------------------------------+--------+------| |Event status |stat |UW | +----------------------------------------------------------------------------+ o stats contains event time information. Following values are available for type in EVENT structure : +----------------------------------------------------------------------------+ |Name | |Concrete contents | |------------+--------+------------------------------------------------------| |GE_BUTDWN |1 |Press event | |------------+--------+------------------------------------------------------| |GE_KEYDWN |3 |Key down event | |------------+--------+------------------------------------------------------| |GE_AUTKEY |3 |Key repeat event | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(C) Text-box-displaying function", the text box is displayed on the screen as a side effect of the system call. (A) For text-box-creating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cid |W | |----------------------------------------------------------+--------+--------| |Text box ID |cid |W | +----------------------------------------------------------------------------+ o Negative cid is error code, and 0 or positive cid is text box ID. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameters |0xfffe0000 |Something other than | | | | |GC_DISABLE is specified in| | | | |parts->type. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |No space in parts | | | | |management table. | +---------------------------------------------------------------------------+ (B) For text-box-deleting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (C) For text-box-displaying function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal Parameter |0xfffe0000 |Illegal mode | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (D) For text-box-setting function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (E) For text-box-obtaining function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Text box current value |val |W | |----------------------------------------------------------+--------+--------| |Character strings area |str |TC* | |----------------------------------------------------------+--------+--------| |Character strings size |size |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive cid is text box current Value. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Text box ID |ID to identify Text box | |--------------------+-------------------------------------------------------| |Character strings |Character area to obtain character strings | |area | | |--------------------+-------------------------------------------------------| |Character strings |Length of character strings area (Unit: TC) | |size | | +----------------------------------------------------------------------------+ (F) For text-box-operating function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |val |W | |----------------------------------------------------------+--------+--------| |Text box current value |val |W | +----------------------------------------------------------------------------+ o Negative val is error code, and 0 or positive cid is parts current Value. o When parts do valid operation, val is ORed with GC_ACT(0x1000). +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal address |0xffff0000 |parts is NULL | |--------+--------------------------+------------+--------------------------| |ER_ID |Illegal ID |0xfffb0000 |Illegal cid | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum total number of text boxes and parts in parts management program is 256 in the entire system. If a text box character string is too long to be displayed completely, the part which exceeds the maximum string length is not displayed. The longest character string length is 20 characters. (5) Remark No remark Appendix 1.5 Data Box Management Function (1) Functional Description In GUI middleware function, this function manages data boxes. The following functions are provided as system calls. (2) Input data An application gives the following input data to data box management function. +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Databox |data |TC* | |----------------------------------------------------------+--------+--------| |ID array |id |W* | |----------------------------------------------------------+--------+--------| |array size |size |W | |----------------------------------------------------------+--------+--------| |Filename |filename|TC* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Data box |Pointer to the databox definition data | |--------------------+-------------------------------------------------------| |ID array |Array to store registered ID | |--------------------+-------------------------------------------------------| |array size |Size of ID array | |--------------------+-------------------------------------------------------| |File name |File name of data box file | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | |----------------------------------------------------------+--------+--------| |Error code |cnt |W | |----------------------------------------------------------+--------+--------| |Number of registration |cnt |W | +----------------------------------------------------------------------------+ o cnt indicates an error code if the value is negative and indicates a number of registration if the value is 0 or positive. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal Address |0xffff0000 |data is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameter |0xfffe0000 |Illegal size and/or | | | | |illegal databox definition| | | | |data. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |More than maximum | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum number of parts for a scene/panel is 32. Since the definition data of data box is referred to even after registration, it must not be released. (5) Remarks No remark (6) Functional block structure and relations Data box management function consists of data box registration function. +--------------------------------------+ |Data Box Management Function | | | | +--------------------------------+ | | | Data box registration function | | | +--------------------------------+ | +--------------------------------------+ Figure Functional block mutual relation in data box management function Appendix 1.5.1 Data box registration function (1) Functional description In data box management function, this registers data boxes. The following functions are provided as system calls. (A) Data box registration function A function to register a data box provided in memory by calling panel management function. (B) Data box file output function A function to output a data box provided in memory to a work file. (C) Data box file input function A function to register a data box provided as a file by calling panel management function. (2) Input data (A) For data box registration function W cnt = gd_reg_dat(TC *data, W *id, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Databox |data |TC* | |----------------------------------------------------------+--------+--------| |ID array |id |W* | |----------------------------------------------------------+--------+--------| |array size |size |W | |----------------------------------------------------------+--------+--------| |Filename |filename|TC* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Data box |Pointer to the databox definition data | |--------------------+-------------------------------------------------------| |ID array |Array to store registered ID | |--------------------+-------------------------------------------------------| |array size |Size of ID array | +----------------------------------------------------------------------------+ Databox definition format : Scene Definition +----------------------------------------------------------------------------+ |Name |Type |Concrete content | |--------+--------+----------------------------------------------------------| |head |TC |GD_SCENE(It means scene definition) | |--------+--------+----------------------------------------------------------| |type |TC |Kind of parts (1st) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |val |TC |Parts current value | |--------+--------+----------------------------------------------------------| |len |TC |Length of parts character strings | |--------+--------+----------------------------------------------------------| |str |TC[len] |Parts character strings | |--------+--------+----------------------------------------------------------| |head |TC |GD_NEXT | |--------+--------+----------------------------------------------------------| |type |TC |Kind of parts (2nd) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |val |TC |Parts current value | |--------+--------+----------------------------------------------------------| |len |TC |Length of parts character strings | |--------+--------+----------------------------------------------------------| |str |TC[len] |Parts character strings | |--------+--------+----------------------------------------------------------| |head |TC |GD_NEXT | |--------+--------+----------------------------------------------------------| |type |TC |Kind of parts (3rd) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |val |TC |Parts current value | |--------+--------+----------------------------------------------------------| |len |TC |Length of parts character strings | |--------+--------+----------------------------------------------------------| |str |TC[len] |Parts character strings | |--------+--------+----------------------------------------------------------| |head |TC |GD_NEXT | +----------------------------------------------------------------------------+ Use contents between GD_NEXT and GD_NEXT as many as needed. Panel definition +----------------------------------------------------------------------------+ |Name |Type |Concrete content | |--------+--------+----------------------------------------------------------| |head |TC |GD_PANEL (It means panel definition) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |type |TC |Kind of parts (1st) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |val |TC |Parts current value | |--------+--------+----------------------------------------------------------| |len |TC |Length of parts character strings | |--------+--------+----------------------------------------------------------| |str |TC[len] |Parts character strings | |--------+--------+----------------------------------------------------------| |head |TC |GD_NEXT | |--------+--------+----------------------------------------------------------| |type |TC |Kind of parts (2nd) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |val |TC |Parts current value | |--------+--------+----------------------------------------------------------| |len |TC |Length of parts character strings | |--------+--------+----------------------------------------------------------| |str |TC[len] |Parts character strings | |--------+--------+----------------------------------------------------------| |head |TC |GD_NEXT | |--------+--------+----------------------------------------------------------| |type |TC |Kind of parts (3rd) | |--------+--------+----------------------------------------------------------| |left |TC |Parts area left | |--------+--------+----------------------------------------------------------| |top |TC |Parts area top | |--------+--------+----------------------------------------------------------| |right |TC |Parts area right | |--------+--------+----------------------------------------------------------| |bottom |TC |Parts area bottom | |--------+--------+----------------------------------------------------------| |val |TC |Parts current value | |--------+--------+----------------------------------------------------------| |len |TC |Length of parts character strings | |--------+--------+----------------------------------------------------------| |str |TC[len] |Parts character strings | |--------+--------+----------------------------------------------------------| |head |TC |GD_NEXT | +----------------------------------------------------------------------------+ Use contents between GD_NEXT and GD_NEXT as many as needed. Termination Definition +----------------------------------------------------------------------------+ |Name |Type |Concrete content | |--------+--------+----------------------------------------------------------| |head |TC |GD_END | +----------------------------------------------------------------------------+ (B) For data box file output function W err = gd_wri_dat(TC *filename, TC *data) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Databox |data |TC* | |----------------------------------------------------------+--------+--------| |File name |filename|TC* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |Data box |Pointer to the databox definition data | |--------------------+-------------------------------------------------------| |File name |File name of databox file | +----------------------------------------------------------------------------+ (C) For data box file input function W cnt = gd_rea_dat(TC *filename, W *id, W size) +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |ID array |id |W* | |----------------------------------------------------------+--------+--------| |array size |size |W | |----------------------------------------------------------+--------+--------| |File name |filename|TC* | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |Name |Meaning | |--------------------+-------------------------------------------------------| |ID array |array to store registered ID | |--------------------+-------------------------------------------------------| |array size |size of ID array | |--------------------+-------------------------------------------------------| |File name |File name of databox file | +----------------------------------------------------------------------------+ (3) Output data The following output data is given to an application. In case of "(B) Data box file output function", a work file is created as a side effect of the system call. (A) For data box registration function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cnt |W | |----------------------------------------------------------+--------+--------| |Number of registration |cnt |W | +----------------------------------------------------------------------------+ o cnt indicates an error code if the value is negative and indicates a number of registration if the value is 0 or positive. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal Address |0xffff0000 |data is NULL | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameter |0xfffe0000 |Illegal size and/or | | | | |illegal databox definition| | | | |data. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |More than maximam | +---------------------------------------------------------------------------+ (B) For data box file output function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |err |W | +----------------------------------------------------------------------------+ Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_ADR |Illegal Address |0xffff0000 |data is NULL | +---------------------------------------------------------------------------+ (C) For data box file input function +----------------------------------------------------------------------------+ |Name |Mnemonic|Type | |----------------------------------------------------------+--------+--------| |Error codes |cnt |W | |----------------------------------------------------------+--------+--------| |Number of registration |cnt |W | +----------------------------------------------------------------------------+ o cnt indicates an error code if the value is negative and indicates a number of registration if the value is 0 or positive. Contents of Error codes : +---------------------------------------------------------------------------+ |Name |Meaning |Value |Concrete Error Content | |--------+--------------------------+------------+--------------------------| |ER_OK |Normal termination |0 |---- | |--------+--------------------------+------------+--------------------------| |ER_PAR |Illegal parameter |0xfffe0000 |Illegal size and/or | | | | |illegal databox definition| | | | |data. | |--------+--------------------------+------------+--------------------------| |ER_NOSPC|Insufficient system memory|0xfffc0000 |More than maximam | +---------------------------------------------------------------------------+ (4) Exception conditions and restrictions The maximum number of parts for a scene/panel is 32. Since the definition data of data box is referred to even after registration, it must not be released. (5) Remark No remark ==============================================================================