Oracle 19c with APPX 5.5.4 on Windows
Set up Oracle as an APPX file system using FMS type 5. Start with one file, then save a record in APPX and check it in Oracle.
APPX 5.5.4 · 32-bit engine Oracle 19c · Oracle Instant Client 19cWhat to install
The example uses a 32-bit APPX 5.5.4 engine on Windows 11 25H2 and a 64-bit Oracle 19c (19.3) database. Install the 32-bit Oracle Instant Client 19c client on the APPX server.
| Component | Download |
|---|---|
| APPX server | Install the 32-bit APPX 5.5.4 engine and set up an APPX Login Manager. APPX 5.5.4 Windows server installer · Installation instructions |
| APPX Desktop Client | Use the 5.5.4 Desktop Client to open an APPX session. Desktop Client installer |
| Oracle | Install Oracle 19c or use an existing server with a dedicated test database. Database installation |
| Oracle client | Match the client to the APPX engine’s 32-bit architecture. Oracle Instant Client 19c 19.32 |
Check the APPX product registration for the Oracle interface. The example uses OCI and FMS type 5.
Choose a database and create a login
Ask your DBA for the host, port, and service name. This single-byte example uses APPXSB with WE8MSWIN1252. Use a dedicated schema or database to rehearse the setup. Replace the example password with a generated value.
Connect as a DBA to the APPXSB service. If this is a pluggable database, connect to the PDB's service. Check its character set before creating the schema owner.
SELECT value FROM nls_database_parameters
WHERE parameter = 'NLS_CHARACTERSET';
CREATE USER APPX_ORA554_DEMO IDENTIFIED BY "use_your_test_password"
DEFAULT TABLESPACE USERS QUOTA 25M ON USERS;
GRANT CREATE SESSION, CREATE TABLE TO APPX_ORA554_DEMO;
Set up the 32-bit Oracle connection
Set the APPX engine’s OCI directory to the 32-bit Instant Client. Create a tnsnames.ora alias named APPXSB for the tested service under TNS_ADMIN.
Extract the Windows x86 Basic and SQL*Plus packages into the same directory. Install the x86 Microsoft Visual C++ Redistributable listed on the Oracle download page. Set APPX_OCI_LIBS to the 19c DLLs in that directory.
APPX_OCI_DIR=C:\oracle\instantclient_19_32
APPX_OCI_LIB=oci.dll
APPX_OCI_LIBS=orannzsbb19.dll;oraociei19.dll
TNS_ADMIN=C:\APPX\oracle-net
NLS_LANG=AMERICAN_AMERICA.WE8MSWIN1252
APPXSB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
(CONNECT_DATA = (SERVICE_NAME = appxsb))
)
Put the 32-bit Instant Client directory before other Oracle client directories on the APPX engine’s PATH. Set TNS_ADMIN and NLS_LANG in the environment that starts the engine. Sign in with sqlplus -L APPX_ORA554_DEMO@APPXSB. Use SHOW USER and SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM dual; to confirm the schema and service.
ORA-12154. Confirm that the running APPX engine sees the same TNS_ADMIN and alias as SQL*Plus. Restart the engine session after correcting its environment.
Unknown error code 202. Check that APPX loads the 32-bit oci.dll and that APPX_OCI_LIBS contains the two DLLs from the 19c Basic package. Clear temporary loader tracing settings APPX_SS_LOG and APPX_SS_CODE, then start a fresh engine session. If Create Files reports Created, confirm the table exists in the target Oracle schema.
Set up the FMS group and identity
Open a new APPX Desktop Client session. Choose System Administration → Configuration → File System Groups under File Maintenance.
- Add
APPX-ORACLEand enter FMS type5. - Click FMS Group Attributes. Enter the values below and save.
| FMS option | Value |
|---|---|
| Server Name | APPXSB |
| Table Naming Scheme | APPX_$db_$appl_$file |
| Tablespace | USERS |
On the group row, click Identities. Enter your APPX user ID to give that user a database login. Leave APPX User blank to set a default identity for the group. Press Enter to accept the key and again to open the details.
Enter APPX_ORA554_DEMO in User Id and leave Realm blank. Save the identity and reopen it in Change mode. Click Change Password, enter the database password, and press Tab to move to Confirm Password. Enter it again and click Change Password. When APPX reports Password Changed, END to Exit, close the password dialog and save the identity. Open a fresh APPX session before testing.
Assign one file and create the table
Use a test database and a file you can create empty. This example uses the Demo Application’s COUNTRY file.
- Open System Administration → Database/Applications → Databases / Applications under File Maintenance. Add
TSTwith the company name Oracle Test. Set the startup application toDMO, version00. Save and accept the report defaults. - For
TST, open Related Applications. AddDMOin Live Operations if it is absent. Select theDMOrow and click Database Management. If APPX prompts for a Language ID, setENGand reopen Database Management. - In File Selection, click Unselect All. Highlight
COUNTRYand press F3. If you use the Select button, enterCOUNTRYin Name and confirm. Return to Data File Management and confirm that one file is selected. - Open File Specifications. Set FMS to
5and FMS Group toAPPX-ORACLEforCOUNTRY. Save and return. - Choose Create Files. The result for
COUNTRYshould say Created.
This naming scheme creates APPX_TST_DMO_COUNTRY in the selected database or schema. For an existing file, follow the APPX/IO migration and rollback guide.
Save and check a record
- From the APPX main menu, choose Run an Application and execute database
TST. In the demo’s top menu, choose Setup → Countries. - In Country Address Format Rules, choose Add. Enter
CANADAfor Country Name,PROVINCEfor Region Label, and2for # Words In Postal Code. Leave Postal Code Location at AFTER REGION. Click Save. - Repeat with
ENCODINGfor Country Name,Québecfor Region Label, and1for # Words In Postal Code. Save. - Open a fresh Desktop Client session, run
TST, and go back to Setup → Countries. Choose Inquire and click First Record if the key field is empty. Find the two keys and confirm the saved values, including the accent inQuébec.
Cannot Access Required File for PROSPECT. In a test database with only COUNTRY created, click Cancel on this message to continue the Countries test. Create the full demo database to run the rest of the application.
Connect independently in SQL*Plus as APPX_ORA554_DEMO. Check the records, encoded value, and unique index on country_name.
SELECT RTRIM(country_name), RTRIM(country_region_label), country_no_words,
DUMP(RTRIM(country_region_label),16) AS stored_bytes
FROM APPX_TST_DMO_COUNTRY ORDER BY country_name;
SELECT i.uniqueness, c.column_name FROM user_indexes i
JOIN user_ind_columns c ON c.index_name=i.index_name
WHERE i.table_name='APPX_TST_DMO_COUNTRY';
Expect CANADA / PROVINCE / 2 and ENCODING / Québec / 1. In the Windows-1252 text, é is byte E9.
Troubleshooting
Check the APPX engine
This guide uses FMS type 5 (Oracle) through the Oracle Call Interface (OCI).
In APPX Release Information, record Engine Release and Compile Date. The application release numbers on the same screen identify the APPX system applications. Match the database client or ODBC driver to the bitness of the engine that runs the operation. Check the settings on the APPX server and under the Windows or Linux account that runs the engine.
Test the connection outside APPX
On the APPX server, use SQL*Plus with the same Oracle alias and database login as APPX. Check TNS_ADMIN and the alias for ORA-12154. For ORA-12514, check the service name with lsnrctl status on the database server and confirm the PDB is open.
If APPX cannot initialize Oracle, check APPX_OCI_DIR, APPX_OCI_LIB, and oci.dll in the 32-bit Instant Client installation. Confirm the required x86 Microsoft Visual C++ Redistributable is installed.
Check the FMS group and Identity
Confirm the FMS group’s Server Name matches the alias that worked in SQL*Plus.
Under Identities, look for an active, unexpired entry for the APPX user running the operation. That entry takes precedence over the blank default. Check User Id and re-enter the database password with Change Password. Save the Identity and open a fresh APPX session. APPX can cache connection and Identity settings for the life of the session.
For ORA-01017, check the password and confirm the user exists in the PDB behind the alias.
Check where APPX creates the table
If the connection succeeds, read the Create Files result or open View Log for the database error. Check the database, login, and target schema or database with the same connection settings as APPX. Compare the APPX database ID, application ID, file name, and Table Naming Scheme with the SQL table name.
Check the PDB, the Oracle user’s current schema, CREATE TABLE, and the schema’s quota on the selected tablespace. ORA-01950 points to a quota problem.
Capture one failing operation
Make a copy of the
appx.envunder the effectiveAPPXPATHof the engine that runs the process. Create a private log directory that the engine account can write to, then temporarily set the variables below. Keep$(pid)as written. The SQL logger replaces it with the engine process ID.APPX_SQL_CMD=C:\APPX\Logs\appx-rdbms-$(pid).log APPX_DBG_CODE=0x1FThe mask includes generated SQL, return statuses, fetch attempts, and engine and connection operations. Use
0xFFFFFFFFfor one attempt if support needs more detail. The engine reads these settings on startup.APPX_ODBC_LOGandAPPX_ODBC_CODEapply to the driver used by external programs to read APPX data.- Keep the Oracle client alias and FMS group you want to diagnose. Use the APPX SQL log and the Oracle error from the failing operation. APPX Oracle debugging
- Open a fresh APPX session and reproduce the failure once. For Create Files, select only the intended test file. For a failed
READwithHOLD, note the APPX error and flags before the nextWRITE. Try a plainREADof the same key in another fresh session. If the log is missing, checkAPPXPATH, the effective variables, and the engine account’s access to the log directory. - Exit the test sessions and restore the previous
appx.envsettings.
If an insert follows a failed held read, keep the first error. A later duplicate-key error indicates that the key existed when the insert ran. Use the insert branch only when the read explicitly reports that the record was absent. Handle lock and database errors before trying another write.
Share the SQL statement, fetch or lock result, and the first SQLSTATE, native error number, and message when available. Include the APPX flags, file and operation, timestamp and time zone, APPX engine release, build date and bitness, operating system, driver name and version, and database versions before and after an upgrade. Keep the SQL structure and error codes intact and replace passwords and record values with placeholders. The APPX SQL log can contain the engine environment and full connection strings. APPX environment settings
If the SQL query returns a different result from the APPX screen, verify the effective FMS group, database, schema, and table name. Restart the APPX session after changing any of them.