]> git.saurik.com Git - wxWidgets.git/blobdiff - src/os2/utils.cpp
applied patch 1737156 to wxAuiManager
[wxWidgets.git] / src / os2 / utils.cpp
index 1d01ee094f1926d294057c7f7b6ca6da26e7b42f..00aafc22cbaf723fac0dab4eeb6d058ee0709af4 100644 (file)
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        utils.cpp
+// Name:        src/os2/utils.cpp
 // Purpose:     Various utilities
 // Author:      David Webster
 // Modified by:
 // For compilers that support precompilation, includes "wx.h".
 #include "wx/wxprec.h"
 
+#include "wx/utils.h"
+
 #ifndef WX_PRECOMP
-    #include "wx/setup.h"
-    #include "wx/utils.h"
-    #include "wx/app.h"
+    #include "wx/intl.h"
+    #include "wx/log.h"
 #endif  //WX_PRECOMP
 
 #include "wx/os2/private.h"
-#include "wx/intl.h"
 #include "wx/apptrait.h"
+#include "wx/filename.h"
 
 #include <ctype.h>
 #ifdef __EMX__
 #include <dirent.h>
 #endif
 
-#include "wx/log.h"
 
 #include <io.h>
 
 
 #define PURE_32
 
-#ifndef __EMX__
-#include <upm.h>
-#include <netcons.h>
-#include <netbios.h>
+#if defined(__WATCOMC__)
+extern "C"
+{
+    #include <upm.h>
+}
+#elif !defined(__EMX__)
+    #include <upm.h>
+    #include <netcons.h>
+    #include <netbios.h>
 #endif
 
-static const wxChar WX_SECTION[] = _T("wxWindows");
+static const wxChar WX_SECTION[] = _T("wxWidgets");
 static const wxChar eHOSTNAME[]  = _T("HostName");
-static const wxChar eUSERID[]    = _T("UserId");
-static const wxChar eUSERNAME[]  = _T("UserName");
 
 // For the following functions we SHOULD fill in support
 // for Windows-NT (which I don't know) as I assume it begin
@@ -56,18 +59,17 @@ static const wxChar eUSERNAME[]  = _T("UserName");
 // functions beyond those provided by WinSock
 
 // Get full hostname (eg. DoDo.BSn-Germany.crg.de)
-bool wxGetHostName(
-  wxChar*                           zBuf
-, int                               nMaxSize
-)
+bool wxGetHostName( wxChar* zBuf, int nMaxSize )
 {
-#if wxUSE_NET_API
-    char                            zServer[256];
-    char                            zComputer[256];
-    unsigned long                   ulLevel = 0;
-    unsigned char*                  zBuffer = NULL;
-    unsigned long                   ulBuffer = 256;
-    unsigned long*                  pulTotalAvail = NULL;
+    if (!zBuf) return false;
+
+#if defined(wxUSE_NET_API) && wxUSE_NET_API
+    char           zServer[256];
+    char           zComputer[256];
+    unsigned long  ulLevel = 0;
+    unsigned char* zBuffer = NULL;
+    unsigned long  ulBuffer = 256;
+    unsigned long* pulTotalAvail = NULL;
 
     NetBios32GetInfo( (const unsigned char*)zServer
                      ,(const unsigned char*)zComputer
@@ -78,61 +80,56 @@ bool wxGetHostName(
                     );
     strcpy(zBuf, zServer);
 #else
-    wxChar*                         zSysname;
-    const wxChar*                   zDefaultHost = _T("noname");
+    wxChar*        zSysname;
+    const wxChar*  zDefaultHost = _T("noname");
 
-    if ((zSysname = wxGetenv(_T("SYSTEM_NAME"))) == NULL)
+    if ((zSysname = wxGetenv(_T("SYSTEM_NAME"))) == NULL &&
+       (zSysname = wxGetenv(_T("HOSTNAME"))) == NULL)
     {
-        ULONG n = ::PrfQueryProfileString( HINI_PROFILE
-                                          ,(PSZ)WX_SECTION
-                                          ,(PSZ)eHOSTNAME
-                                          ,(PSZ)zDefaultHost
-                                          ,(void*)zBuf
-                                          ,(ULONG)nMaxSize - 1
-                                         );
+        ::PrfQueryProfileString( HINI_PROFILE
+                                ,(PSZ)WX_SECTION
+                                ,(PSZ)eHOSTNAME
+                                ,(PSZ)zDefaultHost
+                                ,(void*)zBuf
+                                ,(ULONG)nMaxSize - 1
+                               );
     }
     else
+    {
         wxStrncpy(zBuf, zSysname, nMaxSize - 1);
+    }
+
     zBuf[nMaxSize] = _T('\0');
 #endif
-    return *zBuf ? TRUE : FALSE;
+
+    return *zBuf ? true : false;
 }
 
 // Get user ID e.g. jacs
-bool wxGetUserId(
-  wxChar*                           zBuf
-, int                               nType
-)
+bool wxGetUserId(wxChar* zBuf, int nType)
 {
-#if defined(__VISAGECPP__)
-    long                            lrc;
+#if defined(__VISAGECPP__) || defined(__WATCOMC__)
     // UPM procs return 0 on success
-    lrc = U32ELOCU((unsigned char*)zBuf, (unsigned long *)&nType);
-    if (lrc == 0) return TRUE;
+    long lrc = U32ELOCU((PUCHAR)zBuf, (PULONG)&nType);
+    if (lrc == 0) return true;
 #endif
-    return FALSE;
+    return false;
 }
 
-bool wxGetUserName(
-  wxChar*                           zBuf
-, int                               nMaxSize
-)
+bool wxGetUserName( wxChar* zBuf, int nMaxSize )
 {
 #ifdef USE_NET_API
-    wxGetUserId( zBuf
-                ,nMaxSize
-               );
+    wxGetUserId( zBuf, nMaxSize );
 #else
     wxStrncpy(zBuf, _T("Unknown User"), nMaxSize);
 #endif
-    return TRUE;
+    return true;
 }
 
-int wxKill(
-  long                              lPid
-, wxSignal                          eSig
-, wxKillError*                      peError
-)
+int wxKill(long         lPid,
+           wxSignal     WXUNUSED(eSig),
+           wxKillError* WXUNUSED(peError),
+           int          WXUNUSED(flags))
 {
     return((int)::DosKillProcess(0, (PID)lPid));
 }
@@ -140,29 +137,27 @@ int wxKill(
 //
 // Execute a program in an Interactive Shell
 //
-bool wxShell(
-  const wxString&                   rCommand
-)
+bool wxShell( const wxString& rCommand )
 {
-    wxChar*                         zShell = _T("CMD.EXE");
-    wxString                        sInputs;
-    STARTDATA                       SData = {0};
-    PSZ                             PgmTitle = "Command Shell";
-    APIRET                          rc;
-    PID                             vPid = 0;
-    ULONG                           ulSessID = 0;
-    UCHAR                           achObjBuf[256] = {0}; //error data if DosStart fails
-    RESULTCODES                     vResult;
+    wxChar*     zShell = _T("CMD.EXE");
+    wxString    sInputs;
+    STARTDATA   SData = {0};
+    PSZ         PgmTitle = "Command Shell";
+    APIRET      rc;
+    PID         vPid = 0;
+    ULONG       ulSessID = 0;
+    UCHAR       achObjBuf[256] = {0}; //error data if DosStart fails
+    RESULTCODES vResult;
 
     SData.Length   = sizeof(STARTDATA);
     SData.Related  = SSF_RELATED_INDEPENDENT;
     SData.FgBg     = SSF_FGBG_FORE;
     SData.TraceOpt = SSF_TRACEOPT_NONE;
     SData.PgmTitle = PgmTitle;
-    SData.PgmName  = zShell;
+    SData.PgmName  = (char*)zShell;
 
-    sInputs = "/C " + rCommand;
-    SData.PgmInputs     = (BYTE*)sInputs.c_str();
+    sInputs = _T("/C ") + rCommand;
+    SData.PgmInputs     = (BYTE*)sInputs.wx_str();
     SData.TermQ         = 0;
     SData.Environment   = 0;
     SData.InheritOpt    = SSF_INHERTOPT_SHELL;
@@ -197,25 +192,31 @@ bool wxShell(
 }
 
 // Shutdown or reboot the PC
-bool wxShutdown(wxShutdownFlags wFlags)
+bool wxShutdown(wxShutdownFlags WXUNUSED(wFlags))
 {
     // TODO
-    return FALSE;
+    return false;
 }
 
 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
-long wxGetFreeMemory()
+wxMemorySize wxGetFreeMemory()
 {
-    void*                           pMemptr = NULL;
-    ULONG                           lSize;
-    ULONG                           lMemFlags;
-    APIRET                          rc;
+    void* pMemptr = NULL;
+    LONG  lSize;
+    ULONG lMemFlags;
+    APIRET rc;
 
     lMemFlags = PAG_FREE;
-    rc = ::DosQueryMem(pMemptr, &lSize, &lMemFlags);
+    rc = ::DosQueryMem(pMemptr, (PULONG)&lSize, &lMemFlags);
     if (rc != 0)
-        return -1L;
-    return (long)lSize;
+        lSize = -1L;
+    return (wxMemorySize)lSize;
+}
+
+// Get Process ID
+unsigned long wxGetProcessId()
+{
+    return (unsigned long)getpid();
 }
 
 // ----------------------------------------------------------------------------
@@ -227,21 +228,20 @@ bool wxGetEnv(const wxString& var, wxString *value)
     // wxGetenv is defined as getenv()
     wxChar *p = wxGetenv(var);
     if ( !p )
-        return FALSE;
+        return false;
 
     if ( value )
     {
         *value = p;
     }
 
-    return TRUE;
+    return true;
 }
 
-bool wxSetEnv(const wxString& variable, const wxChar *value)
+bool wxSetEnv(const wxString& variable, const char *value)
 {
 #if defined(HAVE_SETENV)
-    return setenv(variable.mb_str(), value ? wxString(value).mb_str().data()
-                                           : NULL, 1 /* overwrite */) == 0;
+    return setenv(variable.mb_str(), value, 1 /* overwrite */) == 0;
 #elif defined(HAVE_PUTENV)
     wxString s = variable;
     if ( value )
@@ -256,17 +256,36 @@ bool wxSetEnv(const wxString& variable, const wxChar *value)
 
     return putenv(buf) == 0;
 #else // no way to set an env var
-    return FALSE;
+    wxUnusedVar(variable);
+    wxUnusedVar(value);
+    return false;
 #endif
 }
 
-void wxUsleep(
+bool wxSetEnv(const wxString& variable, const wxString& value)
+{
+    return wxDoSetEnv(variable, value.mb_str());
+}
+
+bool wxUnsetEnv(const wxString& variable)
+{
+    return wxDoSetEnv(variable, NULL);
+}
+
+void wxMilliSleep(
   unsigned long                     ulMilliseconds
 )
 {
     ::DosSleep(ulMilliseconds);
 }
 
+void wxMicroSleep(
+  unsigned long                     ulMicroseconds
+)
+{
+    ::DosSleep(ulMicroseconds/1000);
+}
+
 void wxSleep(
   int                               nSecs
 )
@@ -280,89 +299,72 @@ void wxFlushEvents()
 //  wxYield();
 }
 
-#if WXWIN_COMPATIBILITY_2_2
-
-// Output a debug mess., in a system dependent fashion.
-void wxDebugMsg(
-  const wxChar*                     zFmt ...
-)
+// Emit a beeeeeep
+void wxBell()
 {
-    va_list                         vAp;
-    static wxChar                   zBuffer[512];
-
-    if (!wxTheApp->GetWantDebugOutput())
-        return ;
-    va_start(vAp, zFmt);
-    sprintf(zBuffer, zFmt, vAp) ;
-    va_end(vAp);
+    DosBeep(1000,1000); // 1kHz during 1 sec.
 }
 
-// Non-fatal error: pop up message box and (possibly) continue
-void wxError(
-  const wxString&                   rMsg
-, const wxString&                   rTitle
-)
+wxString wxGetOsDescription()
 {
-    wxBuffer = new wxChar[256];
-    wxSprintf(wxBuffer, "%s\nContinue?", WXSTRINGCAST rMsg);
-    if (::WinMessageBox( HWND_DESKTOP
-                        ,NULL
-                        ,(PSZ)wxBuffer
-                        ,(PSZ)WXSTRINGCAST rTitle
-                        ,0
-                        ,MB_ICONEXCLAMATION | MB_YESNO
-                       ) == MBID_YES)
-    delete[] wxBuffer;
-    wxExit();
+    wxString strVer(_T("OS/2"));
+    ULONG ulSysInfo = 0;
+
+    if (::DosQuerySysInfo( QSV_VERSION_MINOR,
+                           QSV_VERSION_MINOR,
+                           (PVOID)&ulSysInfo,
+                           sizeof(ULONG)
+                         ) == 0L )
+    {
+        wxString ver;
+        ver.Printf( _T(" ver. %d.%d"),
+                    int(ulSysInfo / 10),
+                    int(ulSysInfo % 10)
+                  );
+        strVer += ver;
+    }
+
+    return strVer;
 }
 
-// Fatal error: pop up message box and abort
-void wxFatalError(
-  const wxString&                   rMsg
-, const wxString&                   rTitle
-)
+bool wxIsPlatform64Bit()
 {
-    unsigned long                   ulRc;
-
-    ulRc = ::WinMessageBox( HWND_DESKTOP
-                           ,NULL
-                           ,WXSTRINGCAST rMsg
-                           ,WXSTRINGCAST rTitle
-                           ,0
-                           ,MB_NOICON | MB_OK
-                          );
-    DosExit(EXIT_PROCESS, ulRc);
+    // FIXME: No idea how to test for 64 bit processor
+    //        (Probably irrelevant anyhow, though).
+    return false;
 }
 
-#endif // WXWIN_COMPATIBILITY_2_2
+void wxAppTraits::InitializeGui(unsigned long &WXUNUSED(ulHab))
+{
+}
 
-// Emit a beeeeeep
-void wxBell()
+void wxAppTraits::TerminateGui(unsigned long WXUNUSED(ulHab))
 {
-    DosBeep(1000,1000); // 1kHz during 1 sec.
 }
 
-wxToolkitInfo & wxConsoleAppTraits::GetToolkitInfo()
+wxOperatingSystemId wxGetOsVersion(int *verMaj, int *verMin)
 {
-    static wxToolkitInfo           vInfo;
-    ULONG                           ulSysInfo[QSV_MAX] = {0};
-    APIRET                          ulrc;
-
-    vInfo.name = _T("wxBase");
-    ulrc = ::DosQuerySysInfo( 1L
-                             ,QSV_MAX
-                             ,(PVOID)ulSysInfo
-                             ,sizeof(ULONG) * QSV_MAX
+    ULONG                 ulSysInfo = 0;
+    APIRET                ulrc;
+
+    ulrc = ::DosQuerySysInfo( QSV_VERSION_MINOR,
+                              QSV_VERSION_MINOR,
+                              (PVOID)&ulSysInfo,
+                              sizeof(ULONG)
                             );
+
     if (ulrc == 0L)
     {
-        vInfo.versionMajor = ulSysInfo[QSV_VERSION_MAJOR] / 10;
-        vInfo.versionMinor = ulSysInfo[QSV_VERSION_MINOR];
+        if ( verMaj )
+            *verMaj = ulSysInfo / 10;
+        if ( verMin )
+            *verMin = ulSysInfo % 10;
     }
-    vInfo.os = wxOS2_PM;
-    return vInfo;
+
+    return wxOS_OS2;
 }
 
+
 // ---------------------------------------------------------------------------
 const wxChar* wxGetHomeDir(
   wxString*                         pStr
@@ -371,32 +373,40 @@ const wxChar* wxGetHomeDir(
     wxString&                       rStrDir = *pStr;
 
     // OS/2 has no idea about home,
-    // so use the working directory instead?
+    // so use the working directory instead.
+    // However, we might have a valid HOME directory,
+    // as is used on many machines that have unix utilities
+    // on them, so we should use that, if available.
 
     // 256 was taken from os2def.h
 #ifndef MAX_PATH
 #  define MAX_PATH  256
 #endif
 
-    char                            zDirName[256];
-    ULONG                           ulDirLen;
+    const wxChar *szHome = wxGetenv((wxChar*)"HOME");
+    if ( szHome == NULL ) {
+      // we're homeless, use current directory.
+      rStrDir = wxT(".");
+    }
+    else
+       rStrDir = szHome;
 
-    ::DosQueryCurrentDir(0, zDirName, &ulDirLen);
-    rStrDir = zDirName;
     return rStrDir.c_str();
 }
 
 // Hack for OS/2
-wxChar* wxGetUserHome (
-  const wxString&                   rUser
-)
+#if wxUSE_UNICODE
+const wxMB2WXbuf wxGetUserHome( const wxString &rUser )
+#else // just for binary compatibility -- there is no 'const' here
+wxChar* wxGetUserHome ( const wxString &rUser )
+#endif
 {
-    wxChar*                         zHome;
-    wxString                        sUser1(rUser);
+    wxChar*    zHome;
+    wxString   sUser1(rUser);
 
-    wxBuffer = new wxChar[256];
+    wxChar *wxBuffer = new wxChar[256];
 #ifndef __EMX__
-    if (sUser1 != _T(""))
+    if (!sUser1.empty())
     {
         wxChar                      zTmp[64];
 
@@ -414,37 +424,79 @@ wxChar* wxGetUserHome (
                     return *zHome ? zHome : (wxChar*)_T("\\");
             }
             if (wxStricmp(zTmp, WXSTRINGCAST sUser1) == 0)
-                sUser1 = _T("");
+                sUser1 = wxEmptyString;
         }
     }
 #endif
-    if (sUser1 == _T(""))
+    if (sUser1.empty())
     {
         if ((zHome = wxGetenv(_T("HOME"))) != NULL)
         {
             wxStrcpy(wxBuffer, zHome);
             wxUnix2DosFilename(wxBuffer);
+#if wxUSE_UNICODE
+            wxWCharBuffer retBuffer (wxBuffer);
+            delete[] wxBuffer;
+            return retBuffer;
+#else
             wxStrcpy(zHome, wxBuffer);
             delete[] wxBuffer;
             return zHome;
+#endif
         }
     }
     delete[] wxBuffer;
-    return NULL; // No home known!
+    return (wxChar*)wxEmptyString; // No home known!
 }
 
-bool wxDirExists(
-  const wxString&                   rDir
-)
+bool wxGetDiskSpace(const wxString& path,
+                    wxDiskspaceSize_t *pTotal,
+                    wxDiskspaceSize_t *pFree)
 {
-    return (::DosSetCurrentDir(WXSTRINGCAST rDir));
-}
+    if (path.empty())
+        return false;
 
-wxString WXDLLEXPORT wxPMErrorToStr(
-  ERRORID                           vError
-)
+    wxFileName fn(path);
+    FSALLOCATE fsaBuf = {0};
+    APIRET rc = NO_ERROR;
+    ULONG disknum = 0;
+
+    fn.MakeAbsolute();
+
+    if (wxDirExists(fn.GetFullPath()) == false)
+        return false;
+
+    disknum = 1 + wxToupper(fn.GetVolume().GetChar(0)) - _T('A');
+
+    rc = ::DosQueryFSInfo(disknum,             // 1 = A, 2 = B, 3 = C, ...
+                          FSIL_ALLOC,          // allocation info
+                          (PVOID)&fsaBuf,
+                          sizeof(FSALLOCATE));
+
+    if (rc != NO_ERROR)
+        return false;
+    else
+    {
+        if(pTotal)
+        {
+           // to try to avoid 32-bit overflow, let's not multiply right away
+            // (num of alloc units)
+            *pTotal = fsaBuf.cUnit;  
+            // * (num of sectors per alloc unit) * (num of bytes per sector)
+            (*pTotal) *= fsaBuf.cSectorUnit * fsaBuf.cbSector;
+        }
+        if(pFree)
+        {
+            *pFree = fsaBuf.cUnitAvail;
+            (*pFree) *= fsaBuf.cSectorUnit * fsaBuf.cbSector;
+        }
+        return true;
+    }
+}
+wxString wxPMErrorToStr(ERRORID vError)
 {
-    wxString                        sError;
+    wxString sError;
 
     //
     // Remove the high order byte -- it is useless
@@ -492,17 +544,117 @@ wxString WXDLLEXPORT wxPMErrorToStr(
             sError = wxT("Valid name format, but cannot find name in atom table");
             break;
 
+        case PMERR_INV_HPS:
+            sError = wxT("PMERR_INV_HPS");
+            break;
+
+        case PMERR_PS_BUSY:
+            sError = wxT("PMERR_PS_BUSY");
+            break;
+
+        case PMERR_INV_PRIMITIVE_TYPE:
+            sError = wxT("PMERR_INV_PRIMITIVE_TYPE");
+            break;
+
+        case PMERR_UNSUPPORTED_ATTR:
+            sError = wxT("PMERR_UNSUPPORTED_ATTR");
+            break;
+
+        case PMERR_INV_COLOR_ATTR:
+            sError = wxT("PMERR_INV_COLOR_ATTR");
+            break;
+
+        case PMERR_INV_BACKGROUND_COL_ATTR:
+            sError = wxT("PMERR_INV_BACKGROUND_COL_ATTR");
+            break;
+
+        case PMERR_INV_MIX_ATTR:
+            sError = wxT("PMERR_INV_MIX_ATTR");
+            break;
+
+        case PMERR_INV_LINE_WIDTH_ATTR:
+            sError = wxT("PMERR_INV_LINE_WIDTH_ATTR");
+            break;
+
+        case PMERR_INV_GEOM_LINE_WIDTH_ATTR:
+            sError = wxT("PMERR_INV_GEOM_LINE_WIDTH_ATTR");
+            break;
+
+        case PMERR_INV_LINE_TYPE_ATTR:
+            sError = wxT("PMERR_INV_LINE_TYPE_ATTR");
+            break;
+
+        case PMERR_INV_LINE_END_ATTR:
+            sError = wxT("PMERR_INV_LINE_END_ATTR");
+            break;
+
+        case PMERR_INV_LINE_JOIN_ATTR:
+            sError = wxT("PMERR_INV_LINE_JOIN_ATTR");
+            break;
+
+        case PMERR_INV_CHAR_SET_ATTR:
+            sError = wxT("PMERR_INV_CHAR_SET_ATTR");
+            break;
+
+        case PMERR_INV_CHAR_MODE_ATTR:
+            sError = wxT("PMERR_INV_CHAR_MODE_ATTR");
+            break;
+
+        case PMERR_INV_CHAR_DIRECTION_ATTR:
+            sError = wxT("PMERR_INV_CHAR_DIRECTION_ATTR");
+            break;
+
+        case PMERR_INV_CHAR_SHEAR_ATTR:
+            sError = wxT("PMERR_INV_CHAR_SHEAR_ATTR");
+            break;
+
+        case PMERR_INV_CHAR_ANGLE_ATTR:
+            sError = wxT("PMERR_INV_CHAR_ANGLE_ATTR");
+            break;
+
+        case PMERR_INV_MARKER_SET_ATTR:
+            sError = wxT("PMERR_INV_MARKER_SET_ATTR");
+            break;
+
+        case PMERR_INV_MARKER_SYMBOL_ATTR:
+            sError = wxT("PMERR_INV_MARKER_SYMBOL_ATTR");
+            break;
+
+        case PMERR_INV_PATTERN_SET_ATTR:
+            sError = wxT("PMERR_INV_PATTERN_SET_ATTR");
+            break;
+
+        case PMERR_INV_PATTERN_ATTR:
+            sError = wxT("PMERR_INV_PATTERN_ATTR");
+            break;
+
+        case PMERR_INV_COORDINATE:
+            sError = wxT("PMERR_INV_COORDINATE");
+            break;
+
+        case PMERR_UNSUPPORTED_ATTR_VALUE:
+            sError = wxT("PMERR_UNSUPPORTED_ATTR_VALUE");
+            break;
+
+        case PMERR_INV_PATTERN_SET_FONT:
+            sError = wxT("PMERR_INV_PATTERN_SET_FONT");
+            break;
+
+        case PMERR_HUGE_FONTS_NOT_SUPPORTED:
+            sError = wxT("PMERR_HUGE_FONTS_NOT_SUPPORTED");
+            break;
+
         default:
             sError = wxT("Unknown error");
     }
-    return(sError);
+    return sError;
 } // end of wxPMErrorToStr
 
 // replacement for implementation in unix/utilsunx.cpp,
 // to be used by all X11 based ports.
 struct wxEndProcessData;
 
-void wxHandleProcessTermination(wxEndProcessData *proc_data)
+void wxHandleProcessTermination(wxEndProcessData *WXUNUSED(proc_data))
 {
     // For now, just do nothing. To be filled in as needed.
 }